{ "openapi": "3.1.0", "info": { "title": "Mailrith API", "version": "v1", "description": "Mailrith's public API for audience sync, workspace discovery, product control-plane operations, and async subscriber import/export jobs." }, "servers": [ { "url": "https://api.mailrith.com", "description": "Production" }, { "url": "https://api-stage.mailrith.com", "description": "Stage" }, { "url": "http://localhost:8787", "description": "Local development" } ], "tags": [ { "name": "Platform", "description": "Version metadata, discovery URLs, capability discovery, and the machine-readable OpenAPI document." }, { "name": "Workspace", "description": "Read the current authenticated workspace profile and execution context." }, { "name": "Subscribers", "description": "Create or upsert subscribers and list audience records in a workspace." }, { "name": "Tags", "description": "Read and create subscriber tags used for targeting, automation, and imports." }, { "name": "Custom Fields", "description": "Read the typed custom-field schema available to the authenticated workspace." }, { "name": "Email Templates", "description": "Create and manage reusable email templates for the authenticated workspace." }, { "name": "Forms", "description": "Read and manage embeddable form definitions and presentation settings." }, { "name": "Sequences", "description": "Create and manage email sequences, their status, and delivery configuration." }, { "name": "Automations", "description": "Create and manage automation definitions and lifecycle state." }, { "name": "Magic Links", "description": "Create and manage magic links used in broadcasts, sequences, and automations." }, { "name": "Broadcasts", "description": "Create, schedule, test, send, and inspect one-off broadcasts." }, { "name": "Segments", "description": "Read saved segments and preview dynamic audience definitions." }, { "name": "Jobs", "description": "Create and inspect asynchronous subscriber import and export jobs." }, { "name": "Webhooks", "description": "Create and manage outbound webhook subscriptions for Mailrith events and signed event delivery." } ], "components": { "securitySchemes": { "WorkspaceApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Bearer Credential", "description": "Workspace-scoped bearer credential. Mailrith accepts either a workspace API key or an OAuth access token issued to an approved client." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication_error", "permission_error", "not_found", "conflict", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Pagination": { "type": "object", "required": [ "has_more", "next_cursor" ], "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "ApiMetadata": { "type": "object", "required": [ "version", "documentation_url", "reference_url", "agents_url", "sdk_docs_url", "typescript_sdk_url", "python_sdk_url", "mcp_docs_url", "mcp_url", "llms_url", "llms_full_url", "openapi_url", "capabilities_url", "webhook_subscriptions_url", "oauth_authorization_server_url" ], "properties": { "version": { "type": "string" }, "documentation_url": { "type": "string" }, "reference_url": { "type": "string" }, "agents_url": { "type": "string" }, "sdk_docs_url": { "type": "string" }, "typescript_sdk_url": { "type": "string" }, "python_sdk_url": { "type": "string" }, "mcp_docs_url": { "type": "string" }, "mcp_url": { "type": "string" }, "llms_url": { "type": "string" }, "llms_full_url": { "type": "string" }, "openapi_url": { "type": "string" }, "capabilities_url": { "type": "string" }, "webhook_subscriptions_url": { "type": "string" }, "oauth_authorization_server_url": { "type": "string" } } }, "CapabilityOperation": { "type": "object", "required": [ "method", "path", "operation_id", "summary", "required_scopes" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operation_id": { "type": "string" }, "summary": { "type": "string" }, "required_scopes": { "type": "array", "items": { "type": "string" } } } }, "CapabilityResource": { "type": "object", "required": [ "key", "name", "description", "operations" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityOperation" } } } }, "Capabilities": { "type": "object", "required": [ "version", "workspace", "authentication", "credential", "discovery", "sdks", "mcp", "conventions", "events", "resources" ], "properties": { "version": { "type": "string" }, "workspace": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "authentication": { "type": "object", "required": [ "type", "header_name", "header_value_prefix", "workspace_scoped", "scopes_supported", "supported_credential_types" ], "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "header_name": { "type": "string" }, "header_value_prefix": { "type": "string" }, "workspace_scoped": { "type": "boolean" }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "supported_credential_types": { "type": "array", "items": { "type": "string", "enum": [ "workspace_api_key", "oauth_access_token" ] } } } }, "credential": { "oneOf": [ { "type": "object", "required": [ "type", "id", "name", "owner_type", "status", "scopes", "key_preview", "created_at", "updated_at" ], "properties": { "type": { "type": "string", "enum": [ "workspace_api_key" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "owner_type": { "type": "string", "enum": [ "user", "service_account" ] }, "status": { "type": "string", "enum": [ "active", "expired", "revoked", "rotated" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "key_preview": { "type": "string" }, "service_account_id": { "type": "string", "nullable": true }, "service_account_name": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "object", "required": [ "type", "id", "status", "scopes", "token_preview", "client", "approved_by_user_id", "expires_at", "created_at", "updated_at" ], "properties": { "type": { "type": "string", "enum": [ "oauth_access_token" ] }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_preview": { "type": "string" }, "client": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "approved_by_user_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "discovery": { "type": "object", "required": [ "documentation_url", "reference_url", "agents_url", "sdk_docs_url", "typescript_sdk_url", "python_sdk_url", "mcp_docs_url", "mcp_url", "llms_url", "llms_full_url", "openapi_url", "webhook_subscriptions_url", "oauth_authorization_server_url" ], "properties": { "documentation_url": { "type": "string" }, "reference_url": { "type": "string" }, "agents_url": { "type": "string" }, "sdk_docs_url": { "type": "string" }, "typescript_sdk_url": { "type": "string" }, "python_sdk_url": { "type": "string" }, "mcp_docs_url": { "type": "string" }, "mcp_url": { "type": "string" }, "llms_url": { "type": "string" }, "llms_full_url": { "type": "string" }, "openapi_url": { "type": "string" }, "webhook_subscriptions_url": { "type": "string" }, "oauth_authorization_server_url": { "type": "string" } } }, "sdks": { "$ref": "#/components/schemas/PublicApiSdks" }, "mcp": { "$ref": "#/components/schemas/PublicApiMcp" }, "conventions": { "type": "object", "required": [ "pagination_type", "pagination_limit_param", "pagination_cursor_param", "idempotency_header" ], "properties": { "pagination_type": { "type": "string", "enum": [ "cursor" ] }, "pagination_limit_param": { "type": "string" }, "pagination_cursor_param": { "type": "string" }, "idempotency_header": { "type": "string" } } }, "events": { "$ref": "#/components/schemas/WebhookEventSupport" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityResource" } } } }, "PublicApiSdks": { "type": "object", "required": [ "typescript", "python" ], "properties": { "typescript": { "type": "object", "required": [ "package_name", "docs_url", "language" ], "properties": { "package_name": { "type": "string" }, "docs_url": { "type": "string" }, "language": { "type": "string", "enum": [ "typescript" ] } } }, "python": { "type": "object", "required": [ "package_name", "docs_url", "language" ], "properties": { "package_name": { "type": "string" }, "docs_url": { "type": "string" }, "language": { "type": "string", "enum": [ "python" ] } } } } }, "PublicApiMcp": { "type": "object", "required": [ "package_name", "docs_url", "server_url", "recommended_transport", "supported_transports" ], "properties": { "package_name": { "type": "string" }, "docs_url": { "type": "string" }, "server_url": { "type": "string" }, "recommended_transport": { "type": "string", "enum": [ "streamable_http" ] }, "supported_transports": { "type": "array", "items": { "type": "string", "enum": [ "streamable_http", "stdio" ] } } } }, "WebhookSigning": { "type": "object", "required": [ "algorithm", "id_header", "timestamp_header", "signature_header", "signature_prefix" ], "properties": { "algorithm": { "type": "string", "enum": [ "hmac-sha256" ] }, "id_header": { "type": "string" }, "timestamp_header": { "type": "string" }, "signature_header": { "type": "string" }, "signature_prefix": { "type": "string" } } }, "WebhookEventSupport": { "type": "object", "required": [ "subscriptions_url", "supported_events", "supported_event_patterns", "signing" ], "properties": { "subscriptions_url": { "type": "string" }, "supported_events": { "type": "array", "items": { "type": "string" } }, "supported_event_patterns": { "type": "array", "items": { "type": "string" } }, "signing": { "$ref": "#/components/schemas/WebhookSigning" } } }, "WebhookSubscription": { "type": "object", "required": [ "id", "name", "url", "status", "event_patterns", "signing_secret_preview", "delivery_attempts", "last_delivery_status", "last_delivery_error", "last_delivered_at", "last_failed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "event_patterns": { "type": "array", "items": { "type": "string" } }, "signing_secret_preview": { "type": "string" }, "delivery_attempts": { "type": "integer", "minimum": 0 }, "last_delivery_status": { "type": "string", "nullable": true, "enum": [ "delivered", "failed", null ] }, "last_delivery_error": { "type": "string", "nullable": true }, "last_delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "last_failed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionCreateRequest": { "type": "object", "required": [ "name", "url", "event_patterns" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "event_patterns": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "WebhookSubscriptionUpdateRequest": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "event_patterns": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "WebhookSubscriptionCreateResult": { "type": "object", "required": [ "subscription", "signing_secret" ], "properties": { "subscription": { "$ref": "#/components/schemas/WebhookSubscription" }, "signing_secret": { "type": "string" } } }, "WorkspaceReference": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Workspace": { "type": "object", "required": [ "id", "name", "logo", "address", "city", "country", "time_zone", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "time_zone": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TagSummary": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Subscriber": { "type": "object", "required": [ "id", "email", "name", "status", "subscribed_at", "tags", "sequence_ids", "custom_fields", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] }, "subscribed_at": { "type": "string", "format": "date-time" }, "last_opened_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagSummary" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubscriberUpsertRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] }, "subscribed_on": { "type": "string", "example": "2026-04-11", "description": "Subscriber-local subscription date in YYYY-MM-DD format." }, "existing_tag_ids": { "type": "array", "items": { "type": "string" } }, "new_tags": { "type": "array", "items": { "type": "string" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } }, "custom_fields": { "type": "object", "additionalProperties": true } }, "example": { "email": "ada@example.com", "name": "Ada Lovelace", "status": "Active", "existing_tag_ids": [ "tag_existing" ], "new_tags": [ "Website Signup" ], "sequence_ids": [ "sequence_welcome" ], "custom_fields": { "cf_company": "Analytical Engines" } } }, "Tag": { "type": "object", "required": [ "id", "name", "description", "subscriber_count", "double_opt_in_enabled", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "subscriber_count": { "type": "integer" }, "double_opt_in_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TagCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "double_opt_in_enabled": { "type": "boolean" }, "confirmation_email_subject": { "type": "string", "nullable": true }, "confirmation_email_body_document": { "type": "object", "nullable": true, "additionalProperties": true }, "confirmation_success_behavior": { "type": "string", "enum": [ "message", "redirect" ], "nullable": true }, "confirmation_success_message": { "type": "string", "nullable": true }, "confirmation_success_url": { "type": "string", "nullable": true } } }, "CustomField": { "type": "object", "required": [ "id", "label", "type", "required", "settings", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "settings": { "type": "object", "required": [ "options", "checkbox_label" ], "properties": { "options": { "type": "array", "items": { "type": "string" } }, "checkbox_label": { "type": "string", "nullable": true } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Form": { "type": "object", "required": [ "id", "name", "definition", "styles", "subscribers_90d", "submit_url", "embed_url", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "definition": { "type": "object", "additionalProperties": true }, "styles": { "type": "object", "additionalProperties": true }, "subscribers_90d": { "type": "integer" }, "submit_url": { "type": "string" }, "embed_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FormUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "definition": { "type": "object", "additionalProperties": true }, "styles": { "type": "object", "additionalProperties": true } } }, "EmailTemplate": { "type": "object", "required": [ "id", "name", "body", "body_document", "enabled", "workspaces", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "body": { "type": "string" }, "body_document": { "type": "object", "additionalProperties": true }, "enabled": { "type": "boolean" }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceReference" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EmailTemplateUpsertRequest": { "type": "object", "required": [ "name", "body_document" ], "properties": { "name": { "type": "string" }, "body_document": { "type": "object", "additionalProperties": true }, "enabled": { "type": "boolean" } } }, "Sequence": { "type": "object", "required": [ "id", "name", "status", "connection_id", "from_name", "from_email", "reply_to_email", "track_opens", "track_clicks", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "definition", "subscriber_count", "open_rate", "click_rate", "unsubscribed_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused" ] }, "connection_id": { "type": "string", "nullable": true }, "from_name": { "type": "string", "nullable": true }, "from_email": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "definition": { "type": "object", "additionalProperties": true }, "subscriber_count": { "type": "integer" }, "open_rate": { "type": "integer" }, "click_rate": { "type": "integer" }, "unsubscribed_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SequenceUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused" ] }, "connection_id": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "definition": { "type": "object", "additionalProperties": true } } }, "Automation": { "type": "object", "required": [ "id", "name", "status", "definition", "subscriber_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "running", "paused" ] }, "definition": { "type": "object", "additionalProperties": true }, "subscriber_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AutomationUpsertRequest": { "type": "object", "required": [ "name", "definition" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "running", "paused" ] }, "definition": { "type": "object", "additionalProperties": true } } }, "MagicLink": { "type": "object", "required": [ "id", "name", "target_type", "redirect_url", "success_message", "add_tag_ids", "remove_tag_ids", "add_sequence_ids", "remove_sequence_ids", "click_count", "public_url", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "target_type": { "type": "string", "enum": [ "redirect", "message" ] }, "redirect_url": { "type": "string" }, "success_message": { "type": "string" }, "add_tag_ids": { "type": "array", "items": { "type": "string" } }, "remove_tag_ids": { "type": "array", "items": { "type": "string" } }, "add_sequence_ids": { "type": "array", "items": { "type": "string" } }, "remove_sequence_ids": { "type": "array", "items": { "type": "string" } }, "click_count": { "type": "integer" }, "public_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MagicLinkUpsertRequest": { "type": "object", "required": [ "name", "target_type" ], "properties": { "name": { "type": "string" }, "target_type": { "type": "string", "enum": [ "redirect", "message" ] }, "redirect_url": { "type": "string", "nullable": true }, "success_message": { "type": "string", "nullable": true }, "add_tag_ids": { "type": "array", "items": { "type": "string" } }, "remove_tag_ids": { "type": "array", "items": { "type": "string" } }, "add_sequence_ids": { "type": "array", "items": { "type": "string" } }, "remove_sequence_ids": { "type": "array", "items": { "type": "string" } } } }, "Broadcast": { "type": "object", "required": [ "id", "subject", "preview_text", "body", "body_document", "status", "scheduled_at", "completed_at", "connection_id", "from_name", "from_email", "reply_to_email", "audience_definition", "include_tag_ids", "exclude_tag_ids", "include_all_tags", "track_opens", "track_clicks", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "recipient_count", "opened_count", "clicked_count", "unsubscribed_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "preview_text": { "type": "string", "nullable": true }, "body": { "type": "string" }, "body_document": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "scheduled", "running", "completed" ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "connection_id": { "type": "string", "nullable": true }, "from_name": { "type": "string", "nullable": true }, "from_email": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "audience_definition": { "type": "object", "nullable": true, "additionalProperties": true }, "include_tag_ids": { "type": "array", "items": { "type": "string" } }, "exclude_tag_ids": { "type": "array", "items": { "type": "string" } }, "include_all_tags": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "recipient_count": { "type": "integer" }, "opened_count": { "type": "integer" }, "clicked_count": { "type": "integer" }, "unsubscribed_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BroadcastUpsertRequest": { "type": "object", "required": [ "subject", "body_document" ], "properties": { "subject": { "type": "string" }, "preview_text": { "type": "string", "nullable": true }, "body_document": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "connection_id": { "type": "string", "nullable": true }, "reply_to_email": { "type": "string", "nullable": true }, "audience_definition": { "type": "object", "nullable": true, "additionalProperties": true }, "include_tag_ids": { "type": "array", "items": { "type": "string" } }, "exclude_tag_ids": { "type": "array", "items": { "type": "string" } }, "include_all_tags": { "type": "boolean" }, "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true } } }, "BroadcastTestRequest": { "type": "object", "required": [ "recipient" ], "properties": { "recipient": { "type": "string", "format": "email" } } }, "ActionResult": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "completed" ] } } }, "Segment": { "type": "object", "required": [ "id", "name", "description", "definition", "confirmed_subscriber_count", "total_subscriber_count", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "definition": { "type": "object", "additionalProperties": true }, "confirmed_subscriber_count": { "type": "integer" }, "total_subscriber_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SegmentPreviewRequest": { "type": "object", "required": [ "definition" ], "properties": { "definition": { "type": "object", "additionalProperties": true } } }, "SegmentPreview": { "type": "object", "required": [ "confirmed_subscriber_count", "total_subscriber_count" ], "properties": { "confirmed_subscriber_count": { "type": "integer" }, "total_subscriber_count": { "type": "integer" } } }, "SubscriberImportJob": { "type": "object", "required": [ "id", "status", "imported_count", "error_message", "started_at", "completed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Completed", "Failed" ] }, "imported_count": { "type": "integer", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubscriberImportJobCreateRequest": { "type": "object", "required": [ "csv_text", "mappings" ], "properties": { "csv_text": { "type": "string" }, "mappings": { "type": "array", "items": { "type": "object", "required": [ "csv_column", "field" ], "properties": { "csv_column": { "type": "string" }, "field": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "email", "name", "custom-field" ] }, "custom_field_id": { "type": "string", "nullable": true } } } } } }, "new_tag_name": { "type": "string", "nullable": true }, "existing_tag_ids": { "type": "array", "items": { "type": "string" } }, "sequence_ids": { "type": "array", "items": { "type": "string" } } } }, "SubscriberExportJob": { "type": "object", "required": [ "id", "status", "selection", "exported_count", "file_name", "download_url", "expires_at", "error_message", "started_at", "completed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "Queued", "Processing", "Completed", "Failed" ] }, "selection": { "type": "object", "required": [ "query", "status", "cold_only" ], "properties": { "query": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked", null ] }, "cold_only": { "type": "boolean" } } }, "exported_count": { "type": "integer", "nullable": true }, "file_name": { "type": "string", "nullable": true }, "download_url": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubscriberExportJobCreateRequest": { "type": "object", "properties": { "query": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked", null ] }, "cold_only": { "type": "boolean" } } } } }, "paths": { "/v1": { "get": { "method": "GET", "path": "/v1", "summary": "Get API metadata", "description": "Returns the current public API version and discovery links for docs, llms files, the OpenAPI contract, webhook subscriptions, and the authenticated capability endpoint.", "tags": [ "Platform" ], "operationId": "getPublicApiMeta", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMetadata" } } } } } } }, "/v1/capabilities": { "get": { "method": "GET", "path": "/v1/capabilities", "summary": "Get authenticated API capabilities", "description": "Returns the current workspace context, discovery URLs, shared request conventions, supported webhook events, and the public resource operations available to the authenticated bearer credential.", "tags": [ "Platform" ], "operationId": "getPublicApiCapabilities", "security": [ { "WorkspaceApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Capabilities" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/openapi.json": { "get": { "method": "GET", "path": "/v1/openapi.json", "summary": "Get the OpenAPI document", "description": "Returns the machine-readable OpenAPI 3.1 contract for the current public API surface.", "tags": [ "Platform" ], "operationId": "getPublicApiOpenApiDocument", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/workspace": { "get": { "method": "GET", "path": "/v1/workspace", "summary": "Get the current workspace", "description": "Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links.", "tags": [ "Workspace" ], "operationId": "getWorkspace", "security": [ { "WorkspaceApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workspace" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-subscriptions": { "get": { "method": "GET", "path": "/v1/webhook-subscriptions", "summary": "List webhook subscriptions", "description": "Returns the outbound webhook subscriptions configured for the authenticated workspace.", "tags": [ "Webhooks" ], "operationId": "listWebhookSubscriptions", "security": [ { "WorkspaceApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/webhook-subscriptions", "summary": "Create a webhook subscription", "description": "Creates a signed outbound webhook subscription and returns the signing secret once.", "tags": [ "Webhooks" ], "operationId": "createWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest" } } } }, "responses": { "201": { "description": "Webhook subscription created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionCreateResult" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-subscriptions/{webhook_subscription_id}": { "get": { "method": "GET", "path": "/v1/webhook-subscriptions/{webhook_subscription_id}", "summary": "Get a webhook subscription", "description": "Returns a single outbound webhook subscription configured for the authenticated workspace.", "tags": [ "Webhooks" ], "operationId": "getWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "webhook_subscription_id", "in": "path", "required": true, "description": "The webhook subscription identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/webhook-subscriptions/{webhook_subscription_id}", "summary": "Update a webhook subscription", "description": "Updates the destination URL, status, or event pattern set for an existing webhook subscription.", "tags": [ "Webhooks" ], "operationId": "updateWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "webhook_subscription_id", "in": "path", "required": true, "description": "The webhook subscription identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/webhook-subscriptions/{webhook_subscription_id}", "summary": "Delete a webhook subscription", "description": "Deletes an existing outbound webhook subscription from the authenticated workspace.", "tags": [ "Webhooks" ], "operationId": "deleteWebhookSubscription", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "webhook_subscription_id", "in": "path", "required": true, "description": "The webhook subscription identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscription deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/email-templates": { "get": { "method": "GET", "path": "/v1/email-templates", "summary": "List email templates", "description": "Returns reusable email templates linked to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "listEmailTemplates", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/email-templates", "summary": "Create an email template", "description": "Creates a reusable email template scoped to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "createEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateUpsertRequest" } } } }, "responses": { "201": { "description": "Email template created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/email-templates/{template_id}": { "get": { "method": "GET", "path": "/v1/email-templates/{template_id}", "summary": "Get an email template", "description": "Returns a reusable email template linked to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "getEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The email template identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/email-templates/{template_id}", "summary": "Update an email template", "description": "Updates the content or enabled state of an existing email template.", "tags": [ "Email Templates" ], "operationId": "updateEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The email template identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/email-templates/{template_id}", "summary": "Delete an email template", "description": "Deletes an existing email template linked to the authenticated workspace.", "tags": [ "Email Templates" ], "operationId": "deleteEmailTemplate", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "The email template identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Email template deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts": { "get": { "method": "GET", "path": "/v1/broadcasts", "summary": "List broadcasts", "description": "Returns broadcast drafts, scheduled sends, active sends, and completed sends.", "tags": [ "Broadcasts" ], "operationId": "listBroadcasts", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/broadcasts", "summary": "Create a broadcast", "description": "Creates a broadcast draft or scheduled broadcast in the authenticated workspace.", "tags": [ "Broadcasts" ], "operationId": "createBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastUpsertRequest" } } } }, "responses": { "201": { "description": "Broadcast created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}": { "get": { "method": "GET", "path": "/v1/broadcasts/{broadcast_id}", "summary": "Get a broadcast", "description": "Returns a broadcast draft, scheduled send, active send, or completed send.", "tags": [ "Broadcasts" ], "operationId": "getBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/broadcasts/{broadcast_id}", "summary": "Update a broadcast", "description": "Updates a broadcast draft or scheduled send in place.", "tags": [ "Broadcasts" ], "operationId": "updateBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Broadcast" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/broadcasts/{broadcast_id}", "summary": "Delete a broadcast", "description": "Deletes an existing broadcast from the authenticated workspace.", "tags": [ "Broadcasts" ], "operationId": "deleteBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Broadcast deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/send": { "post": { "method": "POST", "path": "/v1/broadcasts/{broadcast_id}/send", "summary": "Send a broadcast now", "description": "Launches immediate delivery for a broadcast draft or scheduled send.", "tags": [ "Broadcasts" ], "operationId": "sendBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Broadcast sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "status", "resource" ], "properties": { "status": { "type": "string", "enum": [ "completed" ] }, "resource": { "$ref": "#/components/schemas/Broadcast" } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/broadcasts/{broadcast_id}/test": { "post": { "method": "POST", "path": "/v1/broadcasts/{broadcast_id}/test", "summary": "Send a broadcast test email", "description": "Sends a test message for an existing broadcast to a single recipient.", "tags": [ "Broadcasts" ], "operationId": "testBroadcast", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "The broadcast identifier.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastTestRequest" } } } }, "responses": { "200": { "description": "Test email sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ActionResult" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences": { "get": { "method": "GET", "path": "/v1/sequences", "summary": "List sequences", "description": "Returns sequences available in the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "listSequences", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sequence" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/sequences", "summary": "Create a sequence", "description": "Creates a sequence in the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "createSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceUpsertRequest" } } } }, "responses": { "201": { "description": "Sequence created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences/{sequence_id}": { "get": { "method": "GET", "path": "/v1/sequences/{sequence_id}", "summary": "Get a sequence", "description": "Returns a sequence in the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "getSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/sequences/{sequence_id}", "summary": "Update a sequence", "description": "Updates an existing sequence in place.", "tags": [ "Sequences" ], "operationId": "updateSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Sequence" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/sequences/{sequence_id}", "summary": "Delete a sequence", "description": "Deletes an existing sequence from the authenticated workspace.", "tags": [ "Sequences" ], "operationId": "deleteSequence", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "description": "The sequence identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sequence deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/automations": { "get": { "method": "GET", "path": "/v1/automations", "summary": "List automations", "description": "Returns automations available in the authenticated workspace.", "tags": [ "Automations" ], "operationId": "listAutomations", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/automations", "summary": "Create an automation", "description": "Creates an automation in the authenticated workspace.", "tags": [ "Automations" ], "operationId": "createAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpsertRequest" } } } }, "responses": { "201": { "description": "Automation created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/automations/{automation_id}": { "get": { "method": "GET", "path": "/v1/automations/{automation_id}", "summary": "Get an automation", "description": "Returns an automation in the authenticated workspace.", "tags": [ "Automations" ], "operationId": "getAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "description": "The automation identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Automation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/automations/{automation_id}", "summary": "Update an automation", "description": "Updates an existing automation in place.", "tags": [ "Automations" ], "operationId": "updateAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "description": "The automation identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/automations/{automation_id}", "summary": "Delete an automation", "description": "Deletes an automation from the authenticated workspace.", "tags": [ "Automations" ], "operationId": "deleteAutomation", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "automation_id", "in": "path", "required": true, "description": "The automation identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Automation deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/magic-links": { "get": { "method": "GET", "path": "/v1/magic-links", "summary": "List magic links", "description": "Returns magic links available in the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "listMagicLinks", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MagicLink" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/magic-links", "summary": "Create a magic link", "description": "Creates a magic link in the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "createMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkUpsertRequest" } } } }, "responses": { "201": { "description": "Magic link created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MagicLink" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/magic-links/{magic_link_id}": { "get": { "method": "GET", "path": "/v1/magic-links/{magic_link_id}", "summary": "Get a magic link", "description": "Returns a magic link in the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "getMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "magic_link_id", "in": "path", "required": true, "description": "The magic link identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MagicLink" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/magic-links/{magic_link_id}", "summary": "Update a magic link", "description": "Updates an existing magic link in place.", "tags": [ "Magic Links" ], "operationId": "updateMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "magic_link_id", "in": "path", "required": true, "description": "The magic link identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MagicLink" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/magic-links/{magic_link_id}", "summary": "Delete a magic link", "description": "Deletes a magic link from the authenticated workspace.", "tags": [ "Magic Links" ], "operationId": "deleteMagicLink", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "magic_link_id", "in": "path", "required": true, "description": "The magic link identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Magic link deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/subscribers": { "get": { "method": "GET", "path": "/v1/subscribers", "summary": "List subscribers", "description": "Returns subscribers in the authenticated workspace, ordered from newest to oldest.", "tags": [ "Subscribers" ], "operationId": "listSubscribers", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "description": "Filter by name, email, or status.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by subscriber status.", "schema": { "type": "string", "enum": [ "Active", "Unconfirmed", "Unsubscribed", "Complained", "Bounced", "Blocked" ] } }, { "name": "cold_only", "in": "query", "description": "When `true`, limit results to cold subscribers.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Maximum number of items to return. Defaults to 25 and is capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscriber" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/subscribers", "summary": "Create or upsert a subscriber", "description": "Creates a new subscriber when the email does not exist in the workspace. If the email already exists, the existing subscriber is updated instead.", "tags": [ "Subscribers" ], "operationId": "upsertSubscriber", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberUpsertRequest" } } } }, "responses": { "200": { "description": "Existing subscriber updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "201": { "description": "Subscriber created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscriber" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tags": { "get": { "method": "GET", "path": "/v1/tags", "summary": "List tags", "description": "Returns tags in the authenticated workspace.", "tags": [ "Tags" ], "operationId": "listTags", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/tags", "summary": "Create a tag", "description": "Creates a new tag in the authenticated workspace.", "tags": [ "Tags" ], "operationId": "createTag", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreateRequest" } } } }, "responses": { "201": { "description": "Tag created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Tag" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/custom-fields": { "get": { "method": "GET", "path": "/v1/custom-fields", "summary": "List custom fields", "description": "Returns custom fields available to the authenticated workspace.", "tags": [ "Custom Fields" ], "operationId": "listCustomFields", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms": { "get": { "method": "GET", "path": "/v1/forms", "summary": "List forms", "description": "Returns forms in the authenticated workspace.", "tags": [ "Forms" ], "operationId": "listForms", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "method": "POST", "path": "/v1/forms", "summary": "Create a form", "description": "Creates a form in the authenticated workspace.", "tags": [ "Forms" ], "operationId": "createForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpsertRequest" } } } }, "responses": { "201": { "description": "Form created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Form" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms/{form_id}": { "get": { "method": "GET", "path": "/v1/forms/{form_id}", "summary": "Get a form", "description": "Returns a form in the authenticated workspace.", "tags": [ "Forms" ], "operationId": "getForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The form identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Form" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "method": "PUT", "path": "/v1/forms/{form_id}", "summary": "Update a form", "description": "Updates an existing form in place.", "tags": [ "Forms" ], "operationId": "updateForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The form identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpsertRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Form" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "method": "DELETE", "path": "/v1/forms/{form_id}", "summary": "Delete a form", "description": "Deletes a form from the authenticated workspace.", "tags": [ "Forms" ], "operationId": "deleteForm", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "form_id", "in": "path", "required": true, "description": "The form identifier.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Form deleted" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/segments": { "get": { "method": "GET", "path": "/v1/segments", "summary": "List segments", "description": "Returns saved segments in the authenticated workspace.", "tags": [ "Segments" ], "operationId": "listSegments", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "starting_after", "in": "query", "description": "Opaque cursor returned by the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/segments/preview": { "post": { "method": "POST", "path": "/v1/segments/preview", "summary": "Preview a segment definition", "description": "Returns subscriber counts for an unsaved audience definition.", "tags": [ "Segments" ], "operationId": "previewSegment", "security": [ { "WorkspaceApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentPreviewRequest" } } } }, "responses": { "200": { "description": "Preview counts", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SegmentPreview" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-imports": { "post": { "method": "POST", "path": "/v1/jobs/subscriber-imports", "summary": "Create a subscriber import job", "description": "Queues an asynchronous subscriber import from CSV text.", "tags": [ "Jobs" ], "operationId": "createSubscriberImportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberImportJobCreateRequest" } } } }, "responses": { "202": { "description": "Import job queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberImportJob" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-imports/{job_id}": { "get": { "method": "GET", "path": "/v1/jobs/subscriber-imports/{job_id}", "summary": "Get a subscriber import job", "description": "Returns the current state of a previously created import job.", "tags": [ "Jobs" ], "operationId": "getSubscriberImportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The import job identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import job", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberImportJob" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-exports": { "post": { "method": "POST", "path": "/v1/jobs/subscriber-exports", "summary": "Create a subscriber export job", "description": "Queues an asynchronous subscriber export for the authenticated workspace.", "tags": [ "Jobs" ], "operationId": "createSubscriberExportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key for safe retries.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriberExportJobCreateRequest" } } } }, "responses": { "202": { "description": "Export job queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberExportJob" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/subscriber-exports/{job_id}": { "get": { "method": "GET", "path": "/v1/jobs/subscriber-exports/{job_id}", "summary": "Get a subscriber export job", "description": "Returns the current state of a previously created export job.", "tags": [ "Jobs" ], "operationId": "getSubscriberExportJob", "security": [ { "WorkspaceApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "The export job identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export job", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SubscriberExportJob" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }