Appearance
API Endpoints
Browse all available XC Scribe API endpoints below. Each endpoint includes request/response schemas, parameters, and example payloads.
API for XC AI Content Automation platform
Servers
https://api.xcscribe.comProduction
https://demoapi.scribe.thextracode.comDemo
http://localhost:8000Local development
Authenticate user credentials
POST
/api/v1/auth/login
Validate email and password, returning a JWT access token on success. If the user has 2FA enabled, returns a temporary token and triggers the 2FA verification flow instead.
Request Body
application/json
JSON "email": "string", "password": "string"
{
}
Responses
Successful Response
application/json
JSON "access_token": "string", "token_type": "bearer", "two_factor_required": false, "two_factor_setup_required": false, "two_factor_method": "string", "temp_token": "string"
{
}
Refresh access token
Logout (revoke current token)
Logout all sessions
Request password reset
Reset password with token
Verify email address
Resend verification email
Self-service registration
POST
/api/v1/auth/register
Create a new account with a Free tier organization. The org starts with 50 XCT.
Request Body
application/json
JSON "email": "string", "password": "string", "company_name": "string", "first_name": "", "last_name": "", "turnstile_token": ""
{
}
Responses
Successful Response
application/json
JSON "access_token": "string", "token_type": "bearer", "organization_id": "string", "message": "string"
{
}
Sign in with Google
POST
/api/v1/auth/google
Verify a Google ID token credential and sign in or create an account.
Request Body
application/json
JSON "credential": "string", "access_token": "string"
{
}
Responses
Successful Response
application/json
JSON "access_token": "string", "token_type": "bearer", "two_factor_required": false, "two_factor_setup_required": false, "two_factor_method": "string", "temp_token": "string"
{
}
Sign in with Apple
POST
/api/v1/auth/apple
Verify an Apple ID token and sign in or create an account.
Request Body
application/json
JSON "id_token": "string", "first_name": "string", "last_name": "string"
{
}
Responses
Successful Response
application/json
JSON "access_token": "string", "token_type": "bearer", "two_factor_required": false, "two_factor_setup_required": false, "two_factor_method": "string", "temp_token": "string"
{
}
Begin 2FA setup
POST
/api/v1/auth/2fa/setup
Initiate two-factor authentication setup for the current user. For TOTP, returns a secret and otpauth URI; for email, sends a verification code.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "method": "string"
{
}
Responses
Successful Response
application/json
JSON "method": "string", "secret": "string", "otpauth_uri": "string", "message": "string"
{
}
Confirm 2FA setup
POST
/api/v1/auth/2fa/confirm
Confirm two-factor authentication setup by verifying a code from the chosen method. Returns a set of one-time backup codes on success.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "code": "string"
{
}
Responses
Successful Response
application/json
JSON "backup_codes": [ "string" ], "message": "string"
{
}
Send 2FA disable code
Disable two-factor authentication
Verify 2FA login code
POST
/api/v1/auth/verify-2fa
Complete the second step of login by verifying a TOTP, email OTP, or backup code. Returns a full JWT access token on success.
Request Body
application/json
JSON "temp_token": "string", "code": "string"
{
}
Responses
Successful Response
application/json
JSON "access_token": "string", "token_type": "bearer", "two_factor_required": false, "two_factor_setup_required": false, "two_factor_method": "string", "temp_token": "string"
{
}
Resend 2FA email code
Begin 2FA setup via temp token
POST
/api/v1/auth/2fa/setup-with-temp
Initiate two-factor authentication setup using a temporary token, intended for organization-enforced 2FA setup during login.
Request Body
application/json
JSON "temp_token": "string", "method": "string"
{
}
Responses
Successful Response
application/json
JSON "method": "string", "secret": "string", "otpauth_uri": "string", "message": "string"
{
}
Confirm 2FA setup via temp token
POST
/api/v1/auth/2fa/confirm-with-temp
Confirm two-factor authentication setup using a temporary token by verifying a code. Returns backup codes on success.
Request Body
application/json
JSON "temp_token": "string", "code": "string"
{
}
Responses
Successful Response
application/json
JSON "backup_codes": [ "string" ], "message": "string"
{
}
users
User management within your organization
Operations
GET/api/v1/usersPOST/api/v1/usersGET/api/v1/users/mePATCH/api/v1/users/meGET/api/v1/users/me/email-preferencesPATCH/api/v1/users/me/email-preferencesGET/api/v1/users/me/chatwoot-identityDELETE/api/v1/users/{user_id}PATCH/api/v1/users/{user_id}POST/api/v1/users/{user_id}/2fa/resetPOST/api/v1/users/{user_id}/2fa/disablePOST/api/v1/users/{user_id}/logout-all
List organization users
GET
/api/v1/users
Returns all users belonging to the admin's organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "role": "string", "is_active": true, "email_verified": false, "is_super_admin": false, "two_factor_enabled": false, "two_factor_method": "string", "oauth_provider": "string", "email_preferences": { "usage_billing": true, "ai_studio": true, "system_alerts": true }, "created_at": "string", "last_login_at": "string", "organization": { "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string" } }
[
]
Create a new user
POST
/api/v1/users
Creates a new user in the admin's organization and sends a welcome email with credentials.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "email": "string", "password": "string", "role": "member"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "role": "string", "is_active": true, "email_verified": false, "is_super_admin": false, "two_factor_enabled": false, "two_factor_method": "string", "oauth_provider": "string", "email_preferences": { "usage_billing": true, "ai_studio": true, "system_alerts": true }, "created_at": "string", "last_login_at": "string", "organization": { "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string" }
{
}
Get current user profile
GET
/api/v1/users/me
Returns the profile of the currently authenticated user.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "role": "string", "is_active": true, "email_verified": false, "is_super_admin": false, "two_factor_enabled": false, "two_factor_method": "string", "oauth_provider": "string", "email_preferences": { "usage_billing": true, "ai_studio": true, "system_alerts": true }, "created_at": "string", "last_login_at": "string", "organization": { "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string" }
{
}
Update current user profile
PATCH
/api/v1/users/me
Updates the authenticated user's own profile fields such as name, phone number, or password.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "current_password": "string", "password": "string", "role": "string", "is_active": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "role": "string", "is_active": true, "email_verified": false, "is_super_admin": false, "two_factor_enabled": false, "two_factor_method": "string", "oauth_provider": "string", "email_preferences": { "usage_billing": true, "ai_studio": true, "system_alerts": true }, "created_at": "string", "last_login_at": "string", "organization": { "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string" }
{
}
Get email notification preferences
Update email notification preferences
PATCH
/api/v1/users/me/email-preferences
Update the current user's email notification preferences.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "usage_billing": true, "ai_studio": true, "system_alerts": true
{
}
Responses
Successful Response
application/json
JSON "usage_billing": true, "ai_studio": true, "system_alerts": true
{
}
Get Chatwoot identity hash
Deactivate a user
Update a user
PATCH
/api/v1/users/{user_id}
Allows an admin to update any user's profile within their organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
user_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "current_password": "string", "password": "string", "role": "string", "is_active": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "first_name": "string", "last_name": "string", "phone_number": "string", "role": "string", "is_active": true, "email_verified": false, "is_super_admin": false, "two_factor_enabled": false, "two_factor_method": "string", "oauth_provider": "string", "email_preferences": { "usage_billing": true, "ai_studio": true, "system_alerts": true }, "created_at": "string", "last_login_at": "string", "organization": { "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string" }
{
}
Reset user 2FA
Disable user 2FA
Force logout a user
Get current organization
GET
/api/v1/organization
Retrieve the organization details associated with the currently authenticated user.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string"
{
}
Update organization details
PATCH
/api/v1/organization
Update the organization's name, settings, address, phone number, tax ID, billing email, or 2FA enforcement. Requires admin privileges.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "enforce_2fa": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string"
{
}
Update organization API keys
PATCH
/api/v1/organization/api-keys
Update the organization's third-party API keys for Anthropic, DeepSeek, or Google. Requires admin privileges and BYOK to be enabled.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "anthropic_api_key": "string", "deepseek_api_key": "string", "google_api_key": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "slug": "string", "settings": { "additionalProperties": "string" }, "address": "string", "phone_number": "string", "tax_id": "string", "billing_email": "string", "byok_enabled": false, "has_anthropic_key": false, "has_deepseek_key": false, "has_google_key": false, "enforce_2fa": false, "created_at": "string"
{
}
Get billing details
GET
/api/v1/organization/billing-details
Retrieve the organization's billing details used for invoicing.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "billing_company_name": "string", "billing_pib": "string", "billing_mb": "string", "billing_address": "string", "billing_city": "string", "billing_postal_code": "string", "billing_country": "string"
{
}
Update billing details
PATCH
/api/v1/organization/billing-details
Update the organization's billing details for invoicing. Requires admin privileges.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "billing_company_name": "string", "billing_pib": "string", "billing_mb": "string", "billing_address": "string", "billing_city": "string", "billing_postal_code": "string", "billing_country": "string"
{
}
Responses
Successful Response
application/json
JSON "billing_company_name": "string", "billing_pib": "string", "billing_mb": "string", "billing_address": "string", "billing_city": "string", "billing_postal_code": "string", "billing_country": "string"
{
}
List custom tones
Create custom tone
POST
/api/v1/organization/tones
Create a new custom tone for the organization. Requires admin privileges. Fails if a tone with the same ID already exists.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "id": "string", "name": "string", "description": "string", "system_prompt": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "description": "string", "system_prompt": "string"
{
}
Delete custom tone
DELETE
/api/v1/organization/tones/{tone_id}
Delete a custom tone by its ID from the organization. Requires admin privileges. Returns 404 if the tone is not found.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tone_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON
[
]
projects
Project lifecycle — create, list, update, delete
Operations
GET/api/v1/projects/plugin-integrationsGET/api/v1/projectsPOST/api/v1/projectsGET/api/v1/projects/{project_id}DELETE/api/v1/projects/{project_id}PATCH/api/v1/projects/{project_id}POST/api/v1/projects/{project_id}/restorePOST/api/v1/projects/{project_id}/truncateDELETE/api/v1/projects/{project_id}/permanent
List plugin integrations
List all projects
GET
/api/v1/projects
Retrieve all projects for the current user's organization. Supports filtering to show only active or only deleted (trashed) projects.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
include_deleted
Type
boolean
Default
falseResponses
Successful Response
application/json
JSON { "id": "string", "name": "string", "platform": "string", "status": "string", "settings": { "additionalProperties": "string" }, "created_at": "string", "completed_at": "string", "item_count": 0, "flagged_count": 0, "source_count": 0, "deleted_at": "string", "status_counts": { "pending": 0, "generated": 0, "flagged": 0, "approved": 0, "rejected": 0, "synced": 0, "excluded": 0 }, "store_connection_id": "string", "store_connection_name": "string", "content_profile_id": "string", "content_profile": { "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string" }, "settings_overrides": { "additionalProperties": "string" } }
[
]
Create a new project
POST
/api/v1/projects
Create a new content project by providing a name and selecting a target platform. The project is initialized in draft status.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/x-www-form-urlencoded
Valid values
"woocommerce""shopify""magento2""wordpress"Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "status": "string", "settings": { "additionalProperties": "string" }, "created_at": "string", "completed_at": "string", "item_count": 0, "flagged_count": 0, "source_count": 0, "deleted_at": "string", "status_counts": { "pending": 0, "generated": 0, "flagged": 0, "approved": 0, "rejected": 0, "synced": 0, "excluded": 0 }, "store_connection_id": "string", "store_connection_name": "string", "content_profile_id": "string", "content_profile": { "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string" }, "settings_overrides": { "additionalProperties": "string" }
{
}
Get project details
GET
/api/v1/projects/{project_id}
Retrieve a single project by ID, including computed item counts and status breakdowns.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "status": "string", "settings": { "additionalProperties": "string" }, "created_at": "string", "completed_at": "string", "item_count": 0, "flagged_count": 0, "source_count": 0, "deleted_at": "string", "status_counts": { "pending": 0, "generated": 0, "flagged": 0, "approved": 0, "rejected": 0, "synced": 0, "excluded": 0 }, "store_connection_id": "string", "store_connection_name": "string", "content_profile_id": "string", "content_profile": { "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string" }, "settings_overrides": { "additionalProperties": "string" }
{
}
Soft-delete a project
Update a project
PATCH
/api/v1/projects/{project_id}
Partially update a project's name, settings, or store connection. Only provided fields are modified.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "name": "string", "settings": { "additionalProperties": "string" }, "store_connection_id": "string", "content_profile_id": "string", "settings_overrides": { "additionalProperties": "string" }
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "status": "string", "settings": { "additionalProperties": "string" }, "created_at": "string", "completed_at": "string", "item_count": 0, "flagged_count": 0, "source_count": 0, "deleted_at": "string", "status_counts": { "pending": 0, "generated": 0, "flagged": 0, "approved": 0, "rejected": 0, "synced": 0, "excluded": 0 }, "store_connection_id": "string", "store_connection_name": "string", "content_profile_id": "string", "content_profile": { "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string" }, "settings_overrides": { "additionalProperties": "string" }
{
}
Restore a deleted project
POST
/api/v1/projects/{project_id}/restore
Restore a previously soft-deleted project from the trash, clearing its deleted timestamp.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "status": "string", "settings": { "additionalProperties": "string" }, "created_at": "string", "completed_at": "string", "item_count": 0, "flagged_count": 0, "source_count": 0, "deleted_at": "string", "status_counts": { "pending": 0, "generated": 0, "flagged": 0, "approved": 0, "rejected": 0, "synced": 0, "excluded": 0 }, "store_connection_id": "string", "store_connection_name": "string", "content_profile_id": "string", "content_profile": { "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string" }, "settings_overrides": { "additionalProperties": "string" }
{
}
Truncate project data
POST
/api/v1/projects/{project_id}/truncate
Delete all content items and data sources from a project while preserving settings. Resets the project to draft status for fresh re-import. Blocked if jobs are currently running.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON
[
]
Permanently delete a project
content
Content generation, review, approval, and export
Operations
POST/api/v1/projects/{project_id}/generatePOST/api/v1/projects/{project_id}/generate/streamPOST/api/v1/projects/{project_id}/regenerate/streamPOST/api/v1/projects/{project_id}/regenerate-rejected/streamPOST/api/v1/projects/{project_id}/regeneratePOST/api/v1/projects/{project_id}/regenerate-rejectedGET/api/v1/projects/{project_id}/itemsPATCH/api/v1/projects/{project_id}/items/batchPOST/api/v1/projects/{project_id}/items/excludePOST/api/v1/projects/{project_id}/items/restorePATCH/api/v1/projects/{project_id}/items/{item_id}POST/api/v1/projects/{project_id}/items/{item_id}/regenerateGET/api/v1/projects/{project_id}/export
Generate content for items
POST
/api/v1/projects/{project_id}/generate
Generates AI content for all pending non-variant items in the project using the specified provider, model, and AI settings. Records token usage and deducts XCT balance.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Stream content generation progress
POST
/api/v1/projects/{project_id}/generate/stream
Generates AI content for pending or selected items via SSE streaming, sending real-time progress events. Uses the specified provider, model, and AI settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Stream full regeneration progress
POST
/api/v1/projects/{project_id}/regenerate/stream
Resets all items to pending and streams AI content regeneration progress via SSE using the specified provider, model, and AI settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Stream rejected items regeneration
POST
/api/v1/projects/{project_id}/regenerate-rejected/stream
Resets only rejected items to pending and streams AI content regeneration progress via SSE using the specified provider, model, and AI settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Regenerate all project content
POST
/api/v1/projects/{project_id}/regenerate
Resets all items to pending and regenerates AI content using the specified provider, model, and AI settings. Records token usage and deducts XCT balance.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Regenerate rejected items only
POST
/api/v1/projects/{project_id}/regenerate-rejected
Resets only rejected items to pending and regenerates AI content using the specified provider, model, and AI settings. Records token usage and deducts XCT balance.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
List project content items
GET
/api/v1/projects/{project_id}/items
Returns all content items for the project, optionally filtered by status or data source.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Query Parameters
status
Type
string
source_id
Type
string
Format
"uuid"Responses
Successful Response
application/json
JSON { "id": "string", "external_id": "string", "item_type": "string", "source_data": { "additionalProperties": "string" }, "generated_content": { "additionalProperties": "string" }, "confidence_score": 0, "status": "string", "ai_model_used": "string", "created_at": "string", "data_source_id": "string", "data_source_name": "string", "metadata": { "additionalProperties": "string" }, "excluded_at": "string", "generation_metadata": { "additionalProperties": "string" } }
[
]
Batch update item statuses
PATCH
/api/v1/projects/{project_id}/items/batch
Updates the status of multiple content items at once within the project.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "item_ids": [ "string" ], "status": "string"
{
}
Responses
Successful Response
application/json
JSON { "id": "string", "external_id": "string", "item_type": "string", "source_data": { "additionalProperties": "string" }, "generated_content": { "additionalProperties": "string" }, "confidence_score": 0, "status": "string", "ai_model_used": "string", "created_at": "string", "data_source_id": "string", "data_source_name": "string", "metadata": { "additionalProperties": "string" }, "excluded_at": "string", "generation_metadata": { "additionalProperties": "string" } }
[
]
Exclude items
POST
/api/v1/projects/{project_id}/items/exclude
Soft-deletes items by setting excluded_at. For Magento configurable parents, cascades to children.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Restore excluded items
POST
/api/v1/projects/{project_id}/items/restore
Restores excluded items by clearing excluded_at. For Magento configurable parents, cascades to children.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Update a content item
PATCH
/api/v1/projects/{project_id}/items/{item_id}
Updates the generated content or status of a single content item.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"item_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "generated_content": { "additionalProperties": "string" }, "status": "string", "metadata": { "additionalProperties": "string" }
{
}
Responses
Successful Response
application/json
JSON "id": "string", "external_id": "string", "item_type": "string", "source_data": { "additionalProperties": "string" }, "generated_content": { "additionalProperties": "string" }, "confidence_score": 0, "status": "string", "ai_model_used": "string", "created_at": "string", "data_source_id": "string", "data_source_name": "string", "metadata": { "additionalProperties": "string" }, "excluded_at": "string", "generation_metadata": { "additionalProperties": "string" }
{
}
Regenerate a single item
POST
/api/v1/projects/{project_id}/items/{item_id}/regenerate
Regenerates AI content for a single content item using the specified provider, model, and AI settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"item_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content_type": "string", "content_variant": "short", "language": "en", "tone": "professional", "ai_provider": "anthropic", "ai_model": "string", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "translate_name": true, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false, "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON "id": "string", "external_id": "string", "item_type": "string", "source_data": { "additionalProperties": "string" }, "generated_content": { "additionalProperties": "string" }, "confidence_score": 0, "status": "string", "ai_model_used": "string", "created_at": "string", "data_source_id": "string", "data_source_name": "string", "metadata": { "additionalProperties": "string" }, "excluded_at": "string", "generation_metadata": { "additionalProperties": "string" }
{
}
Export project content CSV
GET
/api/v1/projects/{project_id}/export
Exports generated content as a CSV file, with platform-specific formatting for Magento. Supports filtering by status, data source, and search query.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Query Parameters
status_filter
Type
string
Default
"approved"source_id
Type
string
Format
"uuid"search
Type
string
Responses
Successful Response
application/json
JSON
[
]
List usage records
GET
/api/v1/usage
Returns AI usage records for the organization, optionally filtered by start and end date.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
start_date
Type
string
Format
"date-time"end_date
Type
string
Format
"date-time"Responses
Successful Response
application/json
JSON { "id": "string", "ai_provider": "string", "ai_model": "string", "content_type": "string", "input_tokens": 0, "output_tokens": 0, "credits_used": 0, "cost_estimate": 0, "created_at": "string" }
[
]
Get usage summary
GET
/api/v1/usage/summary
Aggregates token usage and estimated cost over the specified number of days, broken down by AI provider and content type.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
days
Type
integer
Default
30Responses
Successful Response
application/json
JSON "total_input_tokens": 0, "total_output_tokens": 0, "total_cost": 0, "by_provider": { "additionalProperties": "string" }, "by_content_type": { "additionalProperties": "string" }
{
}
List API keys
GET
/api/v1/api-keys
Returns all API keys for the organization, ordered by most recent first. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "name": "string", "is_active": true, "last_used_at": "string", "created_at": "string" }
[
]
Create API key
POST
/api/v1/api-keys
Generates a new API key for the organization. The raw key is returned only once in the response and cannot be retrieved again. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "key": "string", "created_at": "string"
{
}
Delete API key
Deactivate API key
PATCH
/api/v1/api-keys/{key_id}/deactivate
Deactivates an API key without deleting it, disabling authentication for any client using it. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
key_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "is_active": true, "last_used_at": "string", "created_at": "string"
{
}
sources
Data source management — upload CSV/XML, manual entry
Operations
GET/api/v1/projects/{project_id}/sourcesPOST/api/v1/projects/{project_id}/sources/detect-columnsPOST/api/v1/projects/{project_id}/sources/filePOST/api/v1/projects/{project_id}/sources/manualDELETE/api/v1/projects/{project_id}/sources/{source_id}GET/api/v1/projects/{project_id}/sources/{source_id}/export
List project data sources
GET
/api/v1/projects/{project_id}/sources
Retrieves all data sources for the specified project, ordered by creation date descending, along with a total item count across all sources.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "sources": [ { "id": "string", "project_id": "string", "type": "string", "name": "string", "config": { "additionalProperties": "string" }, "status": "string", "item_count": 0, "last_synced_at": "string", "error_message": "string", "created_at": "string" } ], "total_items": 0
{
}
Detect CSV column mappings
POST
/api/v1/projects/{project_id}/sources/detect-columns
Analyzes CSV headers and sample data to auto-detect column mappings for the project's platform.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
multipart/form-data
Responses
Successful Response
application/json
JSON
[
]
Upload file data source
POST
/api/v1/projects/{project_id}/sources/file
Parses an uploaded file using the project's platform adapter, stores the original file and a snapshot in S3, and creates content items for each parsed product.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
multipart/form-data
Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "type": "string", "name": "string", "config": { "additionalProperties": "string" }, "status": "string", "item_count": 0, "last_synced_at": "string", "error_message": "string", "created_at": "string"
{
}
Create manual data source
POST
/api/v1/projects/{project_id}/sources/manual
Creates an empty manual-entry data source for the specified project, ready to have content items added to it individually.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/x-www-form-urlencoded
Default
"Manual Entry"Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "type": "string", "name": "string", "config": { "additionalProperties": "string" }, "status": "string", "item_count": 0, "last_synced_at": "string", "error_message": "string", "created_at": "string"
{
}
Delete a data source
DELETE
/api/v1/projects/{project_id}/sources/{source_id}
Deletes the specified data source and all of its associated content items via cascade.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"source_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
Export source as CSV
GET
/api/v1/projects/{project_id}/sources/{source_id}/export
Generates a CSV export for a file-based data source by merging generated content back into the original file format using the project's platform adapter.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"source_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON
[
]
List store connections
GET
/api/v1/store-connections
Returns all store connections belonging to the current user's organization, including the number of projects linked to each connection.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "name": "string", "platform": "string", "base_url": "string", "media_base_url": "string", "status": "string", "has_credentials": true, "last_connected_at": "string", "created_at": "string", "updated_at": "string", "project_count": 0 }
[
]
Create store connection
POST
/api/v1/store-connections
Creates a new store connection for the organization. Accepts platform-specific credentials (e.g., access token for Magento/Shopify, consumer key/secret for WooCommerce).
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "platform": "string", "base_url": "string", "media_base_url": "string", "access_token": "string", "consumer_key": "string", "consumer_secret": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "base_url": "string", "media_base_url": "string", "status": "string", "has_credentials": true, "last_connected_at": "string", "created_at": "string", "updated_at": "string", "project_count": 0
{
}
Get store connection
GET
/api/v1/store-connections/{connection_id}
Retrieves a single store connection by ID, including the count of projects currently linked to it.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "base_url": "string", "media_base_url": "string", "status": "string", "has_credentials": true, "last_connected_at": "string", "created_at": "string", "updated_at": "string", "project_count": 0
{
}
Delete store connection
Update store connection
PATCH
/api/v1/store-connections/{connection_id}
Partially updates a store connection's name, URL, credentials, or status. Only provided fields are changed.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "name": "string", "base_url": "string", "media_base_url": "string", "access_token": "string", "consumer_key": "string", "consumer_secret": "string", "status": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "platform": "string", "base_url": "string", "media_base_url": "string", "status": "string", "has_credentials": true, "last_connected_at": "string", "created_at": "string", "updated_at": "string", "project_count": 0
{
}
Test store connection
POST
/api/v1/store-connections/{connection_id}/test
Tests connectivity to the external store by making a live API call. Updates the connection status to active on success or error on failure.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "success": true, "message": "string", "store_name": "string", "media_base_url": "string"
{
}
shopify
Operations
GET/api/v1/shopify/install-urlGET/api/v1/shopify/connectGET/api/v1/shopify/callbackPOST/api/v1/shopify/finalizePOST/api/v1/shopify/webhooks/uninstalledPOST/api/v1/shopify/webhooks/customers/data_requestPOST/api/v1/shopify/webhooks/customers/redactPOST/api/v1/shopify/webhooks/shop/redactPOST/api/v1/shopify/webhooks
Shopify Install Url
Shopify Connect
GET
/api/v1/shopify/connect
Generate Shopify OAuth authorisation URL (used when shop domain is known).
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
shop*
Shopify store domain, e.g. mystore.myshopify.com
Type
Requiredstring
connection_type
Connection type: store or blog
Type
string
Default
"store"Responses
Successful Response
application/json
JSON
[
]
Shopify Callback
Shopify Finalize
POST
/api/v1/shopify/finalize
Finalize a Shopify-initiated install.
Called by the frontend after the user confirms a connection that started
on Shopify's side (the callback had no state). The body carries the
install_token issued by the callback; raw shop/code pairs are not
accepted.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON
[
]
Shopify Uninstalled Webhook
Shopify Customers Data Request
Shopify Customers Redact
Shopify Shop Redact
Shopify Compliance Webhook
POST
/api/v1/shopify/webhooks
Unified compliance webhook endpoint for shopify.app.toml compliance_topics.
Shopify sends all compliance webhooks to this single URI and sets the
X-Shopify-Topic header to distinguish them.
Responses
Successful Response
application/json
JSON
[
]
Stream sync to store
POST
/api/v1/projects/{project_id}/sync/stream
Pushes generated content to the external store via Server-Sent Events. The sync flow selects items by mode (pending, all, or selected), sends each update to the store API, records success/failure in sync history, and streams per-item progress events back to the client.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "mode": "pending", "item_ids": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON
[
]
Sync single item
POST
/api/v1/projects/{project_id}/sync/{item_id}
Pushes a single approved item's generated content to the external store. The sync flow updates the product via the store API, marks the item as synced, and records the result in sync history.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"item_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "success": true, "message": "string", "synced_at": "string"
{
}
Sync all approved items
POST
/api/v1/projects/{project_id}/sync
Pushes all approved items' generated content to the external store in a single batch. The sync flow iterates over every approved item, updates each product via the store API, and returns a summary of successes and failures.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "synced_count": 0, "failed_count": 0, "failed_items": [ { "additionalProperties": "string" } ]
{
}
Get item sync history
GET
/api/v1/projects/{project_id}/sync/{item_id}/history
Returns the chronological sync history for a specific content item, including timestamps, success/failure status, and error messages for each sync attempt.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"item_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "item_id": "string", "item_external_id": "string", "history": [ { "id": "string", "content_item_id": "string", "store_connection_id": "string", "store_connection_name": "string", "synced_at": "string", "success": true, "error_message": "string" } ]
{
}
List project jobs
GET
/api/v1/projects/{project_id}/jobs
Returns up to 50 most recent jobs for a project, optionally filtered by status.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Query Parameters
status
Responses
Successful Response
application/json
JSON { "id": "string", "job_type": "string", "status": "string", "progress_current": 0, "progress_total": 0, "created_at": "string", "started_at": "string", "completed_at": "string", "error": "string" }
[
]
Create background job
POST
/api/v1/projects/{project_id}/jobs
Queues a new background job (generation or sync) for a project. Validates XCT balance for generation jobs and store connection for sync jobs, and rejects the request if a conflicting job is already active.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "job_type": "string", "payload": { "additionalProperties": "string" }
{
}
Responses
Successful Response
application/json
JSON "job_id": "string", "status": "string"
{
}
Get job status
GET
/api/v1/jobs/{job_id}
Returns the current status and progress of a background job. Used for polling job completion.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
job_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "job_type": "string", "status": "string", "progress_current": 0, "progress_total": 0, "progress_detail": [ ], "result": { "additionalProperties": "string" }, "error": "string", "created_at": "string", "started_at": "string", "completed_at": "string"
{
}
Cancel a job
POST
/api/v1/jobs/{job_id}/cancel
Cancels a queued or running job. Jobs that have already completed or failed cannot be cancelled.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
job_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "job_type": "string", "status": "string", "progress_current": 0, "progress_total": 0, "progress_detail": [ ], "result": { "additionalProperties": "string" }, "error": "string", "created_at": "string", "started_at": "string", "completed_at": "string"
{
}
billing
XCT token balance, transactions, and usage
Operations
GET/api/v1/billing/balanceGET/api/v1/billing/transactionsGET/api/v1/billing/usage-summaryGET/api/v1/billing/model-tiersPOST/api/v1/billing/topupGET/api/v1/billing/subscriptionPATCH/api/v1/billing/subscriptionPOST/api/v1/billing/reset-cyclePATCH/api/v1/billing/settingsPOST/api/v1/billing/adjustmentPOST/api/v1/billing/checkoutPOST/api/v1/billing/topup-checkoutGET/api/v1/billing/portalPOST/api/v1/billing/cancel-subscriptionGET/api/v1/billing/payment-historyGET/api/v1/billing/invoices/dodo/{payment_id}/pdfGET/api/v1/billing/paddle/subscriptionPOST/api/v1/billing/paddle/checkoutPOST/api/v1/billing/paddle/topup-checkoutGET/api/v1/billing/paddle/portalPOST/api/v1/billing/invoices/upgradePOST/api/v1/billing/invoices/topupGET/api/v1/billing/invoices/{invoice_id}/pdfGET/api/v1/billing/invoices
Get XCT balance
GET
/api/v1/billing/balance
Returns the organization's current XCT balance broken down by subscription and top-up balances, along with the active subscription tier and overage settings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "subscription_balance": "string", "topup_balance": "string", "total_balance": "string", "subscription_tier": "string", "overage_enabled": true, "token_rate_multiplier": "string"
{
}
List XCT transactions
GET
/api/v1/billing/transactions
Returns a paginated list of all XCT token transactions for the organization, ordered by most recent first.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
page
Type
integer
Minimum
1Default
1page_size
Type
integer
Maximum
100Minimum
1Default
20Responses
Successful Response
application/json
JSON "transactions": [ { "id": "string", "transaction_type": "string", "amount": "string", "balance_type": "string", "description": "string", "created_at": "string", "created_by": "string" } ], "total": 0, "page": 0, "page_size": 0
{
}
Get billing usage summary
GET
/api/v1/billing/usage-summary
Aggregates XCT token consumption for the specified period, grouped by model tier and AI provider.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
days
Type
integer
Maximum
365Minimum
1Default
30Responses
Successful Response
application/json
JSON "period_start": "string", "period_end": "string", "total_xct_used": "string", "by_tier": [ { "tier": "string", "request_count": 0, "total_tokens": 0, "xct_used": "string" } ], "by_provider": { "additionalProperties": "string" }
{
}
List model tier pricing
GET
/api/v1/billing/model-tiers
Returns all available model tiers with their XCT pricing multipliers and the AI models assigned to each tier.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "tiers": [ { "tier": "string", "multiplier": 0, "models": { "additionalProperties": [ { "model_id": "string", "display_name": "string" } ] } } ], "subscription_tier": "string"
{
}
Add XCT top-up
POST
/api/v1/billing/topup
Adds a one-time XCT top-up to the organization's top-up balance. Top-up tokens do not expire on billing cycle reset. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "amount": 0, "description": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "transaction_type": "string", "amount": "string", "balance_type": "string", "description": "string", "created_at": "string", "created_by": "string"
{
}
Get subscription info
GET
/api/v1/billing/subscription
Returns subscription status and payment info for the organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "subscription_tier": "string", "payment_subscription_status": "string", "subscription_period_end": "string", "payment_method": "string", "payment_customer_id": "string", "billing_period": "string", "pending_subscription_tier": "string", "pending_billing_period": "string"
{
}
Change subscription tier
PATCH
/api/v1/billing/subscription
Updates the organization's subscription tier and optionally allocates the new tier's monthly XCT tokens immediately. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "tier": "string", "allocate_immediately": false
{
}
Responses
Successful Response
application/json
JSON "subscription_balance": "string", "topup_balance": "string", "total_balance": "string", "subscription_tier": "string", "overage_enabled": true, "token_rate_multiplier": "string"
{
}
Reset billing cycle
POST
/api/v1/billing/reset-cycle
Manually triggers a subscription billing cycle reset. Expires remaining subscription balance and allocates a fresh monthly XCT allotment. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "subscription_balance": "string", "topup_balance": "string", "total_balance": "string", "subscription_tier": "string", "overage_enabled": true, "token_rate_multiplier": "string"
{
}
Update billing settings
PATCH
/api/v1/billing/settings
Updates billing configuration such as overage enablement and the token rate multiplier for the organization. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "overage_enabled": true, "token_rate_multiplier": 0
{
}
Responses
Successful Response
application/json
JSON "subscription_balance": "string", "topup_balance": "string", "total_balance": "string", "subscription_tier": "string", "overage_enabled": true, "token_rate_multiplier": "string"
{
}
Adjust XCT balance
POST
/api/v1/billing/adjustment
Creates a manual credit or debit adjustment on the organization's subscription or top-up balance. Cannot adjust overage balance directly. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "amount": 0, "balance_type": "string", "description": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "transaction_type": "string", "amount": "string", "balance_type": "string", "description": "string", "created_at": "string", "created_by": "string"
{
}
Create subscription checkout
POST
/api/v1/billing/checkout
Creates a checkout for new subscriptions, or updates an existing subscription for plan changes. Returns checkout_url (Dodo) and/or transaction_id (Paddle) depending on the provider.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "tier": "string", "billing_period": "string"
{
}
Responses
Successful Response
application/json
JSON "checkout_url": "string", "transaction_id": "string", "client_token": "string", "plan_changed": false, "scheduled": false
{
}
Create top-up checkout
POST
/api/v1/billing/topup-checkout
Creates a checkout for purchasing XCT token top-ups.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "packs": 0
{
}
Responses
Successful Response
application/json
JSON "checkout_url": "string", "transaction_id": "string", "client_token": "string"
{
}
Get customer portal URL
Cancel subscription
Get payment history
Download Dodo invoice PDF
Get subscription info (legacy)
GET
/api/v1/billing/paddle/subscription
Legacy endpoint. Returns subscription status with paddle_* field names.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "subscription_tier": "string", "paddle_subscription_status": "string", "subscription_period_end": "string", "payment_method": "string", "paddle_customer_id": "string"
{
}
Create subscription checkout (legacy)
POST
/api/v1/billing/paddle/checkout
Legacy endpoint. Delegates to /billing/checkout.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "tier": "string", "billing_period": "string"
{
}
Responses
Successful Response
application/json
JSON "checkout_url": "string", "transaction_id": "string", "client_token": "string", "plan_changed": false, "scheduled": false
{
}
Create top-up checkout (legacy)
POST
/api/v1/billing/paddle/topup-checkout
Legacy endpoint. Delegates to /billing/topup-checkout.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "packs": 0
{
}
Responses
Successful Response
application/json
JSON "checkout_url": "string", "transaction_id": "string", "client_token": "string"
{
}
Get customer portal URL (legacy)
Self-service plan upgrade
POST
/api/v1/billing/invoices/upgrade
Create a subscription invoice for bank transfer payment. Only for bank transfer customers.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "tier": "string", "billing_period": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "invoice_number": "string", "invoice_type": "string", "amount": "string", "currency": "string", "description": "string", "tier": "string", "billing_period": "string", "xct_amount": "string", "status": "string", "due_date": "string", "paid_at": "string", "confirmed_by": "string", "created_at": "string", "exchange_rate": "string", "eur_amount": "string", "buyer_company_name": "string", "buyer_pib": "string", "buyer_address": "string", "qr_code_data": "string"
{
}
Self-service XCT top-up
POST
/api/v1/billing/invoices/topup
Create a top-up invoice for bank transfer payment.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "xct_packs": 0
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "invoice_number": "string", "invoice_type": "string", "amount": "string", "currency": "string", "description": "string", "tier": "string", "billing_period": "string", "xct_amount": "string", "status": "string", "due_date": "string", "paid_at": "string", "confirmed_by": "string", "created_at": "string", "exchange_rate": "string", "eur_amount": "string", "buyer_company_name": "string", "buyer_pib": "string", "buyer_address": "string", "qr_code_data": "string"
{
}
Download invoice PDF
List My Invoices
GET
/api/v1/billing/invoices
List invoices for the current user's organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "organization_id": "string", "invoice_number": "string", "invoice_type": "string", "amount": "string", "currency": "string", "description": "string", "tier": "string", "billing_period": "string", "xct_amount": "string", "status": "string", "due_date": "string", "paid_at": "string", "confirmed_by": "string", "created_at": "string", "exchange_rate": "string", "eur_amount": "string", "buyer_company_name": "string", "buyer_pib": "string", "buyer_address": "string", "qr_code_data": "string" }
[
]
Validate invitation token
GET
/api/v1/invitations/validate
Validates an invitation token and returns the invitation details. This is the first step in the invitation lifecycle when a user opens an invite link, before they accept.
Parameters
Query Parameters
token*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "email": "string", "organization_name": "string", "role": "string", "is_valid": true
{
}
Accept invitation
POST
/api/v1/invitations/accept
Completes the invitation lifecycle by accepting a pending invitation. Creates a new user account in the organization and marks the invitation as accepted.
Request Body
application/json
JSON "token": "string", "password": "string", "first_name": "string", "last_name": "string"
{
}
Responses
Successful Response
application/json
JSON
[
]
List invitations
GET
/api/v1/invitations
Returns all invitations for the organization across all lifecycle states (pending, accepted, revoked), ordered by most recent first. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "email": "string", "role": "string", "status": "string", "invited_by_email": "string", "created_at": "string", "expires_at": "string", "accepted_at": "string" }
[
]
Create invitation
POST
/api/v1/invitations
Begins the invitation lifecycle by creating a new invitation and sending an email to the invitee. The invitation remains pending until it is accepted, revoked, or expires after 7 days.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "email": "string", "role": "member"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "role": "string", "status": "string", "invited_by_email": "string", "created_at": "string", "expires_at": "string", "accepted_at": "string"
{
}
Resend invitation email
POST
/api/v1/invitations/{invitation_id}/resend
Generates a fresh token, extends the expiry, and resends the invitation email. Only pending invitations in the lifecycle can be resent. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
invitation_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "role": "string", "status": "string", "invited_by_email": "string", "created_at": "string", "expires_at": "string", "accepted_at": "string"
{
}
Revoke invitation
POST
/api/v1/invitations/{invitation_id}/revoke
Terminates the invitation lifecycle by marking a pending invitation as revoked, preventing it from being accepted. Admin only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
invitation_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "email": "string", "role": "string", "status": "string", "invited_by_email": "string", "created_at": "string", "expires_at": "string", "accepted_at": "string"
{
}
Get available import filters
GET
/api/v1/projects/{project_id}/import/filters
Fetches filter options (collections, categories, statuses, etc.) from the project's connected store.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "platform": "string", "filters": { "additionalProperties": [ { "id": "string", "title": "string" } ] }
{
}
Preview import count
POST
/api/v1/projects/{project_id}/import/preview
Counts products matching the given filters without fetching full data. Returns count, estimated batches, and estimated time.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "filters": { "additionalProperties": "string" }
{
}
Responses
Successful Response
application/json
JSON "count": 0, "batches": 0, "estimated_time_seconds": 0
{
}
Start store import
POST
/api/v1/projects/{project_id}/import/execute
Creates a background job to import products matching the filters from the connected store.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "filters": { "additionalProperties": "string" }
{
}
Responses
Successful Response
application/json
JSON "job_id": "string", "estimated_batches": 0
{
}
blog
Blog post creation, editing, and management
Operations
GET/api/v1/projects/{project_id}/blog-postsPOST/api/v1/projects/{project_id}/blog-postsPOST/api/v1/projects/{project_id}/blog-posts/{post_id}/regenerateGET/api/v1/projects/{project_id}/blog-posts/{post_id}DELETE/api/v1/projects/{project_id}/blog-posts/{post_id}PATCH/api/v1/projects/{project_id}/blog-posts/{post_id}POST/api/v1/projects/{project_id}/blog-posts/{post_id}/publishPOST/api/v1/projects/{project_id}/blog-posts/{post_id}/unpublishGET/api/v1/projects/{project_id}/blog-posts/{post_id}/seo-scorePOST/api/v1/projects/{project_id}/blog-posts/{post_id}/schedulePOST/api/v1/projects/{project_id}/blog-posts/{post_id}/unscheduleGET/api/v1/projects/{project_id}/blog-posts/analyticsGET/api/v1/projects/{project_id}/blog-posts/{post_id}/imagesPOST/api/v1/projects/{project_id}/blog-posts/{post_id}/images/from-stockPOST/api/v1/projects/{project_id}/blog-posts/{post_id}/images/uploadPOST/api/v1/projects/{project_id}/blog-posts/{post_id}/images/ai-generateDELETE/api/v1/projects/{project_id}/blog-posts/{post_id}/images/{image_id}GET/api/v1/stock-photos/searchGET/api/v1/stock-photo-keysPOST/api/v1/stock-photo-keysDELETE/api/v1/stock-photo-keys/{key_id}PATCH/api/v1/stock-photo-keys/{key_id}
List blog posts
GET
/api/v1/projects/{project_id}/blog-posts
Returns all blog posts for a project, optionally filtered by status.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Query Parameters
status
Responses
Successful Response
application/json
JSON { "id": "string", "title": "string", "excerpt": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "wp_post_id": 0, "store_connection_id": "string", "external_post_id": "string", "published_url": "string", "published_at": "string", "scheduled_at": "string", "created_at": "string", "updated_at": "string" }
[
]
Create blog post
POST
/api/v1/projects/{project_id}/blog-posts
Creates a new blog post and triggers AI generation via a background job.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "post_type": "string", "topic": "string", "source_item_ids": [ "string" ], "wp_category_ids": [ 0 ], "template_id": "string", "ai_settings": { "additionalProperties": "string" }, "selected_images": [ { "url": "string", "product_name": "string", "alt_text": "string" } ], "store_connection_id": "string", "shopify_blog_id": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Regenerate blog post
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/regenerate
Re-runs AI generation for an existing blog post, creating a new background job.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Get blog post
GET
/api/v1/projects/{project_id}/blog-posts/{post_id}
Returns a single blog post with full content.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Delete blog post
Update blog post
PATCH
/api/v1/projects/{project_id}/blog-posts/{post_id}
Partially updates a blog post's content, title, status, SEO metadata, etc.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_category_ids": [ 0 ], "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }
{
}
Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Publish blog post to WordPress
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/publish
Publishes a blog post to WordPress via the specified blog connection.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "connection_id": "string", "store_connection_id": "string", "wp_status": "publish", "shopify_published": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Unpublish blog post from WordPress
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/unpublish
Sets the WordPress post to draft status and updates the local post status.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Get SEO score
GET
/api/v1/projects/{project_id}/blog-posts/{post_id}/seo-score
Analyzes the blog post for SEO quality and returns a score with recommendations.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Query Parameters
focus_keyword
Responses
Successful Response
application/json
JSON
[
]
Schedule blog post
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/schedule
Schedules a blog post for future publication at the specified time.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "scheduled_at": "string", "connection_id": "string", "store_connection_id": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Unschedule blog post
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/unschedule
Cancels the scheduled publication and reverts to draft.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "organization_id": "string", "title": "string", "content": "string", "excerpt": "string", "slug": "string", "status": "string", "post_type": "string", "topic": "string", "featured_image_url": "string", "seo_meta": { "additionalProperties": "string" }, "wp_post_id": 0, "wp_category_ids": [ 0 ], "published_url": "string", "published_at": "string", "scheduled_at": "string", "blog_connection_id": "string", "store_connection_id": "string", "external_post_id": "string", "external_blog_id": "string", "source_item_ids": [ "string" ], "product_links": { "additionalProperties": "string" }, "ai_settings": { "additionalProperties": "string" }, "template_id": "string", "analytics": { "additionalProperties": "string" }, "job_id": "string", "created_at": "string", "updated_at": "string"
{
}
Blog analytics summary
List blog post images
GET
/api/v1/projects/{project_id}/blog-posts/{post_id}/images
Returns all images attached to a blog post.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON { "id": "string", "blog_post_id": "string", "s3_key": "string", "original_url": "string", "source": "string", "alt_text": "string", "width": 0, "height": 0, "file_size": 0, "variants": { "additionalProperties": "string" }, "created_at": "string", "updated_at": "string" }
[
]
Add image from stock photo
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/images/from-stock
Downloads a stock photo, optimizes it, uploads to S3, and attaches to the blog post.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "photo_url": "string", "alt_text": "string", "photographer": "string", "original_url": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "blog_post_id": "string", "s3_key": "string", "original_url": "string", "source": "string", "alt_text": "string", "width": 0, "height": 0, "file_size": 0, "variants": { "additionalProperties": "string" }, "created_at": "string", "updated_at": "string"
{
}
Upload image
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/images/upload
Upload an image file, optimize it, and attach to the blog post.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Query Parameters
alt_text
Request Body
multipart/form-data
Responses
Successful Response
application/json
JSON "id": "string", "blog_post_id": "string", "s3_key": "string", "original_url": "string", "source": "string", "alt_text": "string", "width": 0, "height": 0, "file_size": 0, "variants": { "additionalProperties": "string" }, "created_at": "string", "updated_at": "string"
{
}
Generate image with AI
POST
/api/v1/projects/{project_id}/blog-posts/{post_id}/images/ai-generate
Generates an image using DALL-E, optimizes it, and attaches to the blog post.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "prompt": "string", "size": "1024x1024", "quality": "standard", "style": "natural"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "blog_post_id": "string", "s3_key": "string", "original_url": "string", "source": "string", "alt_text": "string", "width": 0, "height": 0, "file_size": 0, "variants": { "additionalProperties": "string" }, "created_at": "string", "updated_at": "string"
{
}
Delete blog image
DELETE
/api/v1/projects/{project_id}/blog-posts/{post_id}/images/{image_id}
Deletes a blog image and its S3 files.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
project_id*
Type
Requiredstring
Format
"uuid"post_id*
Type
Requiredstring
Format
"uuid"image_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
Search stock photos
GET
/api/v1/stock-photos/search
Search Pexels for stock photos matching a query.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
q*
Search query
Type
Requiredstring
Min Length
1page
Type
integer
Minimum
1Default
1per_page
Type
integer
Maximum
80Minimum
1Default
20orientation
Responses
Successful Response
application/json
JSON "total_results": 0, "page": 0, "per_page": 0, "photos": [ { "id": 0, "width": 0, "height": 0, "url": "string", "photographer": "string", "photographer_url": "string", "avg_color": "string", "alt": "string", "src": { "additionalProperties": "string" } } ]
{
}
List stock photo keys
GET
/api/v1/stock-photo-keys
Returns all BYOK stock photo provider keys for the organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "organization_id": "string", "provider": "string", "is_active": true, "created_at": "string", "updated_at": "string" }
[
]
Add stock photo key
POST
/api/v1/stock-photo-keys
Add a BYOK API key for a stock photo provider.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "provider": "string", "api_key": "string", "is_active": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "provider": "string", "is_active": true, "created_at": "string", "updated_at": "string"
{
}
Delete stock photo key
Update stock photo key
PATCH
/api/v1/stock-photo-keys/{key_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
key_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "api_key": "string", "is_active": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "provider": "string", "is_active": true, "created_at": "string", "updated_at": "string"
{
}
blog-connections
WordPress blog connections
Operations
GET/api/v1/blog-connectionsPOST/api/v1/blog-connectionsGET/api/v1/blog-connections/{connection_id}DELETE/api/v1/blog-connections/{connection_id}PATCH/api/v1/blog-connections/{connection_id}POST/api/v1/blog-connections/{connection_id}/testGET/api/v1/blog-connections/{connection_id}/categoriesGET/api/v1/blog-connections/shopify/{connection_id}/blogs
List blog connections
GET
/api/v1/blog-connections
Returns all WordPress blog connections for the organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "name": "string", "site_url": "string", "username": "string", "is_active": true, "has_categories": false, "categories_cached_at": "string", "last_synced_at": "string", "created_at": "string", "updated_at": "string" }
[
]
Create blog connection
POST
/api/v1/blog-connections
Adds a new WordPress site connection using Application Password authentication.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "site_url": "string", "username": "string", "app_password": "string"
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "site_url": "string", "username": "string", "is_active": true, "has_categories": false, "categories_cached_at": "string", "last_synced_at": "string", "created_at": "string", "updated_at": "string"
{
}
Get blog connection
GET
/api/v1/blog-connections/{connection_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "site_url": "string", "username": "string", "is_active": true, "has_categories": false, "categories_cached_at": "string", "last_synced_at": "string", "created_at": "string", "updated_at": "string"
{
}
Delete blog connection
Update blog connection
PATCH
/api/v1/blog-connections/{connection_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "name": "string", "site_url": "string", "username": "string", "app_password": "string", "is_active": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "name": "string", "site_url": "string", "username": "string", "is_active": true, "has_categories": false, "categories_cached_at": "string", "last_synced_at": "string", "created_at": "string", "updated_at": "string"
{
}
Test blog connection
POST
/api/v1/blog-connections/{connection_id}/test
Tests connectivity to the WordPress site by verifying credentials.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "success": true, "message": "string", "site_name": "string"
{
}
Get WordPress categories
GET
/api/v1/blog-connections/{connection_id}/categories
Fetches categories from the connected WordPress site. Results are cached.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
connection_id*
Type
Requiredstring
Format
"uuid"Query Parameters
refresh
Type
boolean
Default
falseResponses
Successful Response
application/json
JSON { "id": 0, "name": "string", "slug": "string", "count": 0, "parent": 0 }
[
]
List Shopify blogs
List blog templates
GET
/api/v1/blog-templates
Returns all blog templates for the organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "organization_id": "string", "name": "string", "description": "string", "tone": "string", "structure": { "additionalProperties": "string" }, "custom_instructions": "string", "is_default": true, "created_at": "string", "updated_at": "string" }
[
]
Create blog template
POST
/api/v1/blog-templates
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "description": "string", "tone": "string", "structure": { "additionalProperties": "string" }, "custom_instructions": "string", "is_default": false
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "description": "string", "tone": "string", "structure": { "additionalProperties": "string" }, "custom_instructions": "string", "is_default": true, "created_at": "string", "updated_at": "string"
{
}
Get blog template
GET
/api/v1/blog-templates/{template_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
template_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "description": "string", "tone": "string", "structure": { "additionalProperties": "string" }, "custom_instructions": "string", "is_default": true, "created_at": "string", "updated_at": "string"
{
}
Delete blog template
Update blog template
PATCH
/api/v1/blog-templates/{template_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
template_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "name": "string", "description": "string", "tone": "string", "structure": { "additionalProperties": "string" }, "custom_instructions": "string", "is_default": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "description": "string", "tone": "string", "structure": { "additionalProperties": "string" }, "custom_instructions": "string", "is_default": true, "created_at": "string", "updated_at": "string"
{
}
Request Data Export
Get Gdpr Status
Request Account Deletion
POST
/api/v1/gdpr/request-deletion
Permanently delete the organization and all associated data.
Deletion is immediate — all data is erased and cannot be recovered.
Invoices are anonymized (not deleted) to meet legal retention requirements.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "password": ""
{
}
Responses
Successful Response
application/json
JSON "message": "string"
{
}
Get unread notification count
List notifications
GET
/api/v1/notifications
Returns paginated notifications for the current user, ordered by most recent first.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
limit
Type
integer
Maximum
100Minimum
1Default
20offset
Type
integer
Minimum
0Default
0Responses
Successful Response
application/json
JSON "notifications": [ { "id": "string", "notification_type": "string", "title": "string", "body": "string", "project_id": "string", "job_id": "string", "data": { "additionalProperties": "string" }, "is_read": true, "created_at": "string" } ], "total": 0, "has_more": true
{
}
Mark notification as read
POST
/api/v1/notifications/{notification_id}/read
Marks a single notification as read.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
notification_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "notification_type": "string", "title": "string", "body": "string", "project_id": "string", "job_id": "string", "data": { "additionalProperties": "string" }, "is_read": true, "created_at": "string"
{
}
Mark all notifications as read
List studio requests
GET
/api/v1/studio-requests
Returns studio requests for the current user's organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
status
limit
Type
integer
Maximum
100Minimum
1Default
20offset
Type
integer
Minimum
0Default
0Responses
Successful Response
application/json
JSON "requests": [ { "id": "string", "organization_id": "string", "user_id": "string", "user_name": "string", "user_email": "string", "description": "string", "budget_range": "string", "exclusivity": true, "status": "string", "priority": 0, "comment_count": 0, "latest_comment_at": "string", "created_at": "string", "updated_at": "string" } ], "total": 0, "has_more": true
{
}
Submit a new AI Studio quote request
POST
/api/v1/studio-requests
Creates a new custom AI project request for the current user's organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "description": "string", "budget_range": "string", "exclusivity": false
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "user_id": "string", "user_name": "string", "user_email": "string", "description": "string", "budget_range": "string", "exclusivity": true, "status": "string", "priority": 0, "comment_count": 0, "latest_comment_at": "string", "created_at": "string", "updated_at": "string"
{
}
Get studio request detail
GET
/api/v1/studio-requests/{request_id}
Returns a studio request with its public comments.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
request_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "user_id": "string", "user_name": "string", "user_email": "string", "organization_name": "string", "description": "string", "budget_range": "string", "exclusivity": true, "status": "string", "priority": 0, "comments": [ { "id": "string", "request_id": "string", "user_id": "string", "user_name": "string", "user_email": "string", "content": "string", "is_internal": true, "created_at": "string" } ], "created_at": "string", "updated_at": "string"
{
}
Add a comment to a studio request
POST
/api/v1/studio-requests/{request_id}/comments
Adds a customer comment to their organization's request.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
request_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "content": "string", "is_internal": false
{
}
Responses
Successful Response
application/json
JSON "id": "string", "request_id": "string", "user_id": "string", "user_name": "string", "user_email": "string", "content": "string", "is_internal": true, "created_at": "string"
{
}
Chatwoot Webhook
Chatwoot Email Webhook
Tenant Webhook
POST
/api/v1/chatbot/tenant-webhook
Generic multi-tenant webhook endpoint.
Each tenant registers this URL in Chatwoot with their own account_id and
webhook_secret as the token query param.
Parameters
Query Parameters
account_id*
Type
Requiredinteger
token*
Type
Requiredstring
Responses
Successful Response
application/json
JSON
[
]
Plugin Status
Plugin Generate Description
POST
/api/v1/plugin/generate-description
Generate a product description via the plugin API.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "source": "string", "product_title": "string", "product_category": "string", "product_attributes": { "additionalProperties": "string" }, "product_images": [ "string" ], "current_description": "string", "language": "en", "tone": "professional", "custom_instructions": "string"
{
}
Responses
Successful Response
application/json
JSON "content": "string", "short_description": "string", "tokens_used": 0, "xct_cost": "string", "remaining_balance": "string"
{
}
Plugin Generate Description Async
POST
/api/v1/plugin/generate-description-async
Start async product description generation. Returns generation_id for polling.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "source": "string", "product_title": "string", "product_category": "string", "product_attributes": { "additionalProperties": "string" }, "product_images": [ "string" ], "current_description": "string", "language": "en", "tone": "professional", "custom_instructions": "string"
{
}
Responses
Successful Response
application/json
JSON "generation_id": "string"
{
}
Plugin Generate Blog
POST
/api/v1/plugin/generate-blog
Generate a blog post via the plugin API.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "source": "string", "topic": "string", "product_title": "string", "product_category": "string", "language": "en", "tone": "professional", "custom_instructions": "string"
{
}
Responses
Successful Response
application/json
JSON "content": "string", "short_description": "string", "tokens_used": 0, "xct_cost": "string", "remaining_balance": "string"
{
}
Plugin Generate Blog Async
POST
/api/v1/plugin/generate-blog-async
Start async blog generation. Returns generation_id for polling.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "source": "string", "topic": "string", "product_title": "string", "product_category": "string", "language": "en", "tone": "professional", "custom_instructions": "string"
{
}
Responses
Successful Response
application/json
JSON "generation_id": "string"
{
}
Plugin Generation Status
GET
/api/v1/plugin/generation/{generation_id}/status
Poll generation status.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
generation_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "status": "string", "content": "string", "short_description": "string", "tokens_used": 0, "xct_cost": "string", "remaining_balance": "string", "error": "string"
{
}
List Profiles
GET
/api/v1/content-profiles
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string" }
[
]
Create Profile
POST
/api/v1/content-profiles
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "ai_provider": "anthropic", "ai_model": "string", "language": "en", "tone": "professional", "custom_instructions": "string", "max_short_chars": 200, "max_long_chars": 1000, "use_html": true, "use_html_short": false, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": false, "image_analysis_count": 3, "structured_data_enabled": false, "generate_bullet_points": false, "generate_attributes": false, "generate_tags": false
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string"
{
}
Get Profile
GET
/api/v1/content-profiles/{profile_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
profile_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string"
{
}
Update Profile
PUT
/api/v1/content-profiles/{profile_id}
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
profile_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "name": "string", "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true
{
}
Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string"
{
}
Delete Profile
Set Default Profile
PUT
/api/v1/content-profiles/{profile_id}/set-default
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
profile_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "organization_id": "string", "name": "string", "is_default": true, "ai_provider": "string", "ai_model": "string", "language": "string", "tone": "string", "custom_instructions": "string", "max_short_chars": 0, "max_long_chars": 0, "use_html": true, "use_html_short": true, "generate_short": true, "generate_long": true, "translate_name": true, "image_analysis_enabled": true, "image_analysis_count": 0, "structured_data_enabled": true, "generate_bullet_points": true, "generate_attributes": true, "generate_tags": true, "created_at": "string", "updated_at": "string"
{
}
List Studio Tools
GET
/api/v1/studio/tools
List all visible studio tools with unlock status for the current user.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "tools": [ { "id": "string", "slug": "string", "name": "string", "description": "string", "icon": "string", "min_tier": "string", "unlocked": true } ]
{
}
Run Audit
POST
/api/v1/studio/store-audit/run
Start a store audit for all products in a project.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "project_id": "string", "enabled_checks": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON "audit_id": "string", "job_id": "string", "estimated_products": 0, "estimated_xct": "string"
{
}
List Audits
GET
/api/v1/studio/store-audit
List audits for the current org, optionally filtered by project.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
project_id
Responses
Successful Response
application/json
JSON "audits": [ { "id": "string", "project_id": "string", "job_id": "string", "status": "string", "product_count": 0, "health_score": 0, "summary": { "additionalProperties": "string" }, "xct_used": "string", "created_at": "string", "completed_at": "string", "error": "string" } ]
{
}
Get Audit
GET
/api/v1/studio/store-audit/{audit_id}
Get audit results including per-product findings.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
audit_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "id": "string", "project_id": "string", "job_id": "string", "status": "string", "product_count": 0, "health_score": 0, "summary": { "additionalProperties": "string" }, "xct_used": "string", "created_at": "string", "completed_at": "string", "error": "string", "products": [ { "id": "string", "content_item_id": "string", "product_title": "string", "product_url": "string", "description_word_count": 0, "description_preview": "string", "issues": [ "string" ], "scores": { "additionalProperties": "string" } } ]
{
}
Delete Audit
Create Fix Project
POST
/api/v1/studio/store-audit/{audit_id}/create-fix-project
Create a new project pre-loaded with products that have a specific issue.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
audit_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "issue_type": "string"
{
}
Responses
Successful Response
application/json
JSON "project_id": "string", "product_count": 0
{
}
List Templates
GET
/api/v1/studio/profile-builder/templates
List all available content profile templates.
Responses
Successful Response
application/json
JSON { "id": "string", "name": "string", "description": "string", "icon": "string", "defaults": { "additionalProperties": "string" } }
[
]
Generate Instructions
POST
/api/v1/studio/profile-builder/generate
Generate AI-crafted custom instructions from a template and brand context.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "template_id": "string", "brand_name": "", "target_audience": "", "unique_selling_points": "", "tone": "professional", "language": "en", "things_to_avoid": ""
{
}
Responses
Successful Response
application/json
JSON "custom_instructions": "string", "xct_used": 0
{
}
tenants
Operations
GET/api/v1/tenantsGET/api/v1/tenants/minePOST/api/v1/tenants/request-accessGET/api/v1/tenants/{tenant_id}/knowledge-sourcesPOST/api/v1/tenants/{tenant_id}/knowledge-sources/urlDELETE/api/v1/tenants/{tenant_id}/knowledge-sources/{source_id}POST/api/v1/tenants/{tenant_id}/knowledge-sources/{source_id}/syncPOST/api/v1/tenants/{tenant_id}/knowledge-sources/upload-urlPOST/api/v1/tenants/{tenant_id}/knowledge-sources/uploadPATCH/api/v1/tenants/{tenant_id}/content-profileGET/api/v1/tenants/{tenant_id}/custom-attributesPATCH/api/v1/tenants/{tenant_id}/custom-attributesPOST/api/v1/tenants/{tenant_id}/storeDELETE/api/v1/tenants/{tenant_id}/storePATCH/api/v1/tenants/{tenant_id}/store-settingsGET/api/v1/tenants/{tenant_id}/analytics
List My Tenants
GET
/api/v1/tenants
Return all active tenants in the caller's organization, ordered by id.
Organizations with multiple tenants (e.g. Ivan owning both LolaWOOF and
XTRACODE) use this to populate the tenant switcher in the chatbot UI.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON { "id": 0, "name": "string", "chatwoot_account_id": 0, "collection": "string", "mode": "string", "status": "string", "slack_channel_id": "string", "store_id": "string", "content_profile_id": "string", "product_lookup_enabled": true, "product_lookup_include_oos": true, "organization_id": "string", "created_at": "string", "updated_at": "string" }
[
]
Get My Tenant
GET
/api/v1/tenants/mine
Return the tenant owned by the caller's organization.
Multi-tenant chatbot assumes a single Tenant row per organization — this
endpoint resolves the current user's organization to its Tenant or returns
404 when the organization has no chatbot provisioned yet.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "id": 0, "name": "string", "chatwoot_account_id": 0, "collection": "string", "mode": "string", "status": "string", "slack_channel_id": "string", "store_id": "string", "content_profile_id": "string", "product_lookup_enabled": true, "product_lookup_include_oos": true, "organization_id": "string", "created_at": "string", "updated_at": "string"
{
}
Request Access
POST
/api/v1/tenants/request-access
Record a contact-form submission and notify staff on Slack.
Rate-limited to 3 requests per authenticated user per rolling 24 hours to
avoid abuse. Slack notification failures are swallowed by the notifier so
they never fail the request — the DB row is the source of truth.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Request Body
application/json
JSON "company_name": "string", "contact_email": "string", "contact_phone": "string", "website": "string", "use_case": "string", "expected_volume": "string", "desired_channels": [ "string" ]
{
}
Responses
Successful Response
application/json
JSON "id": 0, "status": "string"
{
}
List Knowledge Sources
GET
/api/v1/tenants/{tenant_id}/knowledge-sources
List knowledge sources for a tenant, annotated with chunk counts.
Chunk counts come from a single aggregate query over
chatbot_document_chunks filtered by the tenant's collection so the
response never requires N+1 round-trips.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Responses
Successful Response
application/json
JSON { "id": 0, "source_type": "string", "source_value": "string", "refresh_schedule": "string", "last_synced_at": "string", "last_error": "string", "enabled": true, "chunk_count": 0 }
[
]
Add Url Source
POST
/api/v1/tenants/{tenant_id}/knowledge-sources/url
Create a URL-type knowledge source and enqueue the sync task.
The Celery task is imported lazily so tests can patch
src.worker.tasks_chatbot.sync_knowledge_source before calling the
endpoint.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Request Body
application/json
JSON "source_value": "string", "refresh_schedule": "manual"
{
}
Responses
Successful Response
application/json
JSON "id": 0, "source_type": "string", "source_value": "string", "refresh_schedule": "string", "last_synced_at": "string", "last_error": "string", "enabled": true, "chunk_count": 0
{
}
Delete Knowledge Source
Trigger Sync
POST
/api/v1/tenants/{tenant_id}/knowledge-sources/{source_id}/sync
Re-enqueue the Celery sync task for an existing knowledge source.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
source_id*
Type
Requiredinteger
Responses
Successful Response
application/json
JSON "additionalProperties": true
{
}
Get Upload Url
POST
/api/v1/tenants/{tenant_id}/knowledge-sources/upload-url
Return a pre-signed S3 PUT URL for uploading a knowledge document.
The frontend calls this first, PUTs the file directly to S3 using the
returned URL, then calls POST /knowledge-sources/upload with the
returned s3_key to register the source and enqueue the sync.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Query Parameters
filename*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Register Uploaded File
POST
/api/v1/tenants/{tenant_id}/knowledge-sources/upload
Register a file already PUT to S3 and enqueue the sync task.
The S3 key must live under this tenant's upload prefix
(chatbot/uploads/{tenant.id}/...) — callers can't register files
belonging to other tenants.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Request Body
application/json
JSON "s3_key": "string", "original_filename": "string"
{
}
Responses
Successful Response
application/json
JSON "id": 0, "source_type": "string", "source_value": "string", "refresh_schedule": "string", "last_synced_at": "string", "last_error": "string", "enabled": true, "chunk_count": 0
{
}
Link Content Profile
PATCH
/api/v1/tenants/{tenant_id}/content-profile
Attach a Content Profile owned by the caller's org to the tenant.
The profile's organization_id must match the tenant's — this prevents
tenant admins from linking to another organization's profile even if they
somehow know its UUID.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Request Body
application/json
JSON "content_profile_id": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Custom Attributes
GET
/api/v1/tenants/{tenant_id}/custom-attributes
Return the TenantBehaviorOverride row, or empty defaults if none.
The chatbot reads these three values from tenant_behavior_overrides
ahead of any Chatwoot fallback; exposing them to the admin UI lets the
Behavior panel hydrate its inputs with the current saved state without
having to persist shadow copies client-side.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Update Custom Attributes
PATCH
/api/v1/tenants/{tenant_id}/custom-attributes
Upsert TenantBehaviorOverride row for this tenant.
Writes the three behavior fields locally instead of round-tripping to
Chatwoot — TenantConfigFetcher prefers this row over the Chatwoot
fallback. We also invalidate the in-process fetcher cache so the bot
picks up the change on the next message.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Request Body
application/json
JSON "default_language": "string", "handoff_phrases": [ "string" ], "redirect_url_for_products": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": true
{
}
Link Store
POST
/api/v1/tenants/{tenant_id}/store
Link a StoreConnection owned by the caller's org to the tenant.
The store's organization_id must match the tenant's — otherwise an
admin could attach another organisation's store to their tenant just by
knowing its UUID.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Request Body
application/json
JSON "store_id": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Unlink Store
Update Store Settings
PATCH
/api/v1/tenants/{tenant_id}/store-settings
Toggle product-lookup flags on the tenant.
Only fields explicitly supplied in the payload are written — omitting a
field leaves its current value alone so the UI can PATCH one toggle at
a time.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant_id*
Type
Requiredinteger
Request Body
application/json
JSON "product_lookup_enabled": true, "product_lookup_include_oos": true
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": true
{
}