{ "openapi": "3.1.0", "info": { "title": "LetterCraft Public API", "version": "1.0.0", "description": "REST API for programmatic newsletter generation and delivery.\n\n**Auth:** Bearer token (`Authorization: Bearer lc_live_…`). Issue keys at https://lettercraft.email/dashboard/api.\n**Plan:** All endpoints require the API plan.\n**Rate limits:** 60 req/min per key for read/write endpoints; 10 req/min for AI endpoints (`/newsletter/generate`, `/newsletter/translate`, `/crawl`).\n**Quota:** 500 AI generations per calendar month, shared with your dashboard usage.\n\nAll responses are JSON with a top-level `ok` boolean. Errors include `error` (string) and may include `quota`.", "contact": { "name": "Support", "url": "https://lettercraft.email/contact" } }, "servers": [ { "url": "https://lettercraft.email/api/public/v1" } ], "tags": [ { "name": "Newsletters", "description": "Generate, save, list, update, delete drafts." }, { "name": "Brand voices", "description": "Reusable tone, audience, banned words, signature." }, { "name": "Recipient lists", "description": "Lists + members + bulk import + unsubscribe." }, { "name": "Senders", "description": "Sender profiles used as the From address." }, { "name": "Sending", "description": "Send-now, schedule, recurring cadence, outbox." }, { "name": "Translations", "description": "Pre-translate a generated newsletter." }, { "name": "Crawl & uploads", "description": "Crawl source URLs, upload images / PDFs / audio." }, { "name": "Webhooks", "description": "Subscribe to events emitted by your account." }, { "name": "Account", "description": "Quota and usage." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lc_live_…" } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "Quota": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetAt": { "type": "string", "format": "date-time" } } }, "GenerateInput": { "type": "object", "required": [ "brief" ], "properties": { "brief": { "type": "string", "minLength": 8, "maxLength": 4000, "description": "What the newsletter is about." }, "language": { "type": "string", "enum": [ "en", "de", "fr", "es", "ar" ], "default": "en" }, "tone": { "type": "string", "enum": [ "professional", "friendly", "casual", "authoritative", "playful" ], "default": "professional" }, "length": { "type": "string", "enum": [ "short", "medium", "long" ], "default": "medium" }, "audience": { "type": "string", "maxLength": 300 }, "sources": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 10 }, "requiredQuotes": { "type": "array", "items": { "type": "string", "maxLength": 800 }, "maxItems": 10 }, "brandVoice": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "audience": { "type": "string", "maxLength": 300 }, "styleNotes": { "type": "string", "maxLength": 2000 }, "bannedWords": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "signature": { "type": "string", "maxLength": 500 } } } } }, "NewsletterBlock": { "type": "object", "properties": { "type": { "type": "string", "description": "e.g. heading, paragraph, quote, image, list, cta" }, "content": { "type": "string" }, "level": { "type": "integer" }, "items": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } }, "additionalProperties": true }, "GenerateResult": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "result": { "type": "object", "properties": { "subject": { "type": "string" }, "preheader": { "type": "string" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/NewsletterBlock" } }, "html": { "type": "string", "description": "Rendered HTML" }, "markdown": { "type": "string" }, "plainText": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "sourceNotes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "missingQuotes": { "type": "array", "items": { "type": "string" } } } }, "quota": { "$ref": "#/components/schemas/Quota" } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "prompt": { "type": "string" }, "language": { "type": "string" }, "tone": { "type": "string" }, "length": { "type": "string" }, "audience": { "type": "string" }, "blocks": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "ready", "sent" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BrandVoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "style_notes": { "type": "string" }, "banned_words": { "type": "array", "items": { "type": "string" } }, "signature": { "type": "string" }, "is_default": { "type": "boolean" }, "allow_translation": { "type": "boolean" } } }, "RecipientList": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "member_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "Member": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true, "enum": [ "en", "de", "fr", "es", "ar", null ] }, "unsubscribed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Sender": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "privacy_url": { "type": "string", "format": "uri", "nullable": true }, "provider": { "type": "string", "enum": [ "lovable", "resend" ] }, "verified": { "type": "boolean" } } }, "Schedule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "list_id": { "type": "string", "format": "uuid" }, "sender_profile_id": { "type": "string", "format": "uuid" }, "cadence": { "type": "string", "enum": [ "once", "weekly", "monthly" ] }, "next_run_at": { "type": "string", "format": "date-time" }, "last_run_at": { "type": "string", "format": "date-time", "nullable": true }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "canceled" ] } } }, "OutboxItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "list_id": { "type": "string", "format": "uuid", "nullable": true }, "to_email": { "type": "string", "format": "email", "nullable": true }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sent", "failed" ] }, "scheduled_for": { "type": "string", "format": "date-time", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/newsletter/generate": { "post": { "summary": "Generate a newsletter", "tags": [ "Newsletters" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateResult" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateInput" } } } } } }, "/projects": { "get": { "summary": "List your saved newsletter projects", "tags": [ "Newsletters" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create or update a project (omit `id` to create)", "tags": [ "Newsletters" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "If present, updates this project" }, "title": { "type": "string", "maxLength": 200 }, "prompt": { "type": "string", "maxLength": 4000 }, "language": { "type": "string", "enum": [ "en", "de", "fr", "es", "ar" ] }, "tone": { "type": "string" }, "length": { "type": "string" }, "audience": { "type": "string" }, "blocks": { "type": "object", "additionalProperties": true } } } } } } } }, "/projects/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Load a project", "tags": [ "Newsletters" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a project", "tags": [ "Newsletters" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brand-voices": { "get": { "summary": "List your brand voice profiles", "tags": [ "Brand voices" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create or update a brand voice (omit `id` to create)", "tags": [ "Brand voices" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandVoice" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 80 }, "tone": { "type": "string" }, "audience": { "type": "string" }, "styleNotes": { "type": "string" }, "bannedWords": { "type": "array", "items": { "type": "string" } }, "signature": { "type": "string" }, "isDefault": { "type": "boolean" }, "allowTranslation": { "type": "boolean" } } } } } } } }, "/brand-voices/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Delete a brand voice", "tags": [ "Brand voices" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lists": { "get": { "summary": "List recipient lists", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a recipient list", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientList" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 400 } } } } } } } }, "/lists/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Delete a list and its members", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lists/{id}/members": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "List members of a list", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add a single recipient", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "de", "fr", "es", "ar" ] } } } } } } } }, "/lists/{id}/members/import": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "summary": "Bulk-import recipients (up to 50,000)", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Import summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "total": { "type": "integer" }, "inserted": { "type": "integer" }, "duplicatesInFile": { "type": "integer" }, "duplicatesInList": { "type": "integer" }, "invalid": { "type": "integer" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rows" ], "properties": { "fileName": { "type": "string" }, "rows": { "type": "array", "maxItems": 50000, "items": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "de", "fr", "es", "ar" ] } } } } } } } } } } }, "/lists/{listId}/members/{memberId}": { "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Remove a recipient from a list", "tags": [ "Recipient lists" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/senders": { "get": { "summary": "List your sender profiles", "tags": [ "Senders" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a sender profile", "tags": [ "Senders" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sender" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "address": { "type": "string" }, "privacyUrl": { "type": "string", "format": "uri" } } } } } } } }, "/senders/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Delete a sender profile", "tags": [ "Senders" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sending/send": { "post": { "summary": "Send a one-off newsletter immediately", "tags": [ "Sending" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "projectId", "listId", "senderProfileId", "subject" ], "properties": { "projectId": { "type": "string", "format": "uuid" }, "listId": { "type": "string", "format": "uuid" }, "senderProfileId": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "maxLength": 200 } } } } } } } }, "/sending/schedule": { "post": { "summary": "Create a one-off or recurring schedule", "tags": [ "Sending" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "projectId", "listId", "senderProfileId", "cadence", "subject" ], "properties": { "projectId": { "type": "string", "format": "uuid" }, "listId": { "type": "string", "format": "uuid" }, "senderProfileId": { "type": "string", "format": "uuid" }, "cadence": { "type": "string", "enum": [ "once", "weekly", "monthly" ] }, "scheduledFor": { "type": "string", "format": "date-time" }, "subject": { "type": "string", "maxLength": 200 } } } } } } } }, "/sending/schedules": { "get": { "summary": "List your schedules", "tags": [ "Sending" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "projectId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ] } }, "/sending/schedules/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Cancel a schedule", "tags": [ "Sending" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sending/outbox": { "get": { "summary": "List outbox items (queued, sent, failed)", "tags": [ "Sending" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "projectId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500, "default": 100 } } ] } }, "/crawl": { "post": { "summary": "Crawl a URL and return extracted text + metadata", "tags": [ "Crawl & uploads" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } } } }, "/webhooks": { "get": { "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Endpoint created. The `secret` is shown ONCE.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "HMAC secret — store now." } } } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "newsletter.generated", "newsletter.sent", "newsletter.failed" ] } } } } } } } } }, "/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "delete": { "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Missing/invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Plan does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate-limited or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/usage": { "get": { "summary": "Get current month's quota and usage", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Usage snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "tier": { "type": "string" }, "generations": { "$ref": "#/components/schemas/Quota" }, "sends": { "type": "object", "properties": { "used": { "type": "integer" }, "quota": { "type": "integer" }, "remaining": { "type": "integer" } } } } } } } } } } } } }