Appearance
API Endpoints
Browse all available 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
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"
}
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,
"is_super_admin": false,
"two_factor_enabled": false,
"two_factor_method": "string",
"created_at": "string",
"last_login_at": "string",
"organization": {
"id": "string",
"name": "string",
"slug": "string",
"settings": {
},
"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,
"is_super_admin": false,
"two_factor_enabled": false,
"two_factor_method": "string",
"created_at": "string",
"last_login_at": "string",
"organization": {
"id": "string",
"name": "string",
"slug": "string",
"settings": {
},
"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,
"is_super_admin": false,
"two_factor_enabled": false,
"two_factor_method": "string",
"created_at": "string",
"last_login_at": "string",
"organization": {
"id": "string",
"name": "string",
"slug": "string",
"settings": {
},
"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",
"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,
"is_super_admin": false,
"two_factor_enabled": false,
"two_factor_method": "string",
"created_at": "string",
"last_login_at": "string",
"organization": {
"id": "string",
"name": "string",
"slug": "string",
"settings": {
},
"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"
}
}
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",
"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,
"is_super_admin": false,
"two_factor_enabled": false,
"two_factor_method": "string",
"created_at": "string",
"last_login_at": "string",
"organization": {
"id": "string",
"name": "string",
"slug": "string",
"settings": {
},
"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
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": {
},
"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": {
},
"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": {
},
"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": {
},
"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"
}
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
[
]
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": {
},
"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"
}
]
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"Responses
Successful Response
application/json
JSON
{
"id": "string",
"name": "string",
"platform": "string",
"status": "string",
"settings": {
},
"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"
}
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": {
},
"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"
}
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": {
},
"store_connection_id": "string"
}
Responses
Successful Response
application/json
JSON
{
"id": "string",
"name": "string",
"platform": "string",
"status": "string",
"settings": {
},
"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"
}
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": {
},
"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"
}
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,
"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,
"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,
"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,
"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,
"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,
"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": {
},
"generated_content": {
},
"confidence_score": 0,
"status": "string",
"ai_model_used": "string",
"created_at": "string",
"data_source_id": "string",
"data_source_name": "string",
"metadata": {
},
"excluded_at": "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": {
},
"generated_content": {
},
"confidence_score": 0,
"status": "string",
"ai_model_used": "string",
"created_at": "string",
"data_source_id": "string",
"data_source_name": "string",
"metadata": {
},
"excluded_at": "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": {
},
"status": "string",
"metadata": {
}
}
Responses
Successful Response
application/json
JSON
{
"id": "string",
"external_id": "string",
"item_type": "string",
"source_data": {
},
"generated_content": {
},
"confidence_score": 0,
"status": "string",
"ai_model_used": "string",
"created_at": "string",
"data_source_id": "string",
"data_source_name": "string",
"metadata": {
},
"excluded_at": "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,
"item_ids": [
"string"
]
}
Responses
Successful Response
application/json
JSON
{
"id": "string",
"external_id": "string",
"item_type": "string",
"source_data": {
},
"generated_content": {
},
"confidence_score": 0,
"status": "string",
"ai_model_used": "string",
"created_at": "string",
"data_source_id": "string",
"data_source_name": "string",
"metadata": {
},
"excluded_at": "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": {
},
"by_content_type": {
}
}
List API keys
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": {
},
"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
Format
"binary"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
Format
"binary"Responses
Successful Response
application/json
JSON
{
"id": "string",
"project_id": "string",
"type": "string",
"name": "string",
"config": {
},
"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": {
},
"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",
"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",
"access_token": "string",
"consumer_key": "string",
"consumer_secret": "string"
}
Responses
Successful Response
application/json
JSON
{
"id": "string",
"name": "string",
"platform": "string",
"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",
"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",
"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",
"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"
}
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": [
{
}
]
}
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": {
}
}
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": {
},
"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": {
},
"error": "string",
"created_at": "string",
"started_at": "string",
"completed_at": "string"
}
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": [
]
}
}
]
}
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"
}
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": null
}
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"
}
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": [
]
}
}
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": {
}
}
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": {
}
}
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",
"status": "string",
"post_type": "string",
"topic": "string",
"featured_image_url": "string",
"wp_post_id": 0,
"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": {
}
}
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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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": {
},
"wp_category_ids": [
0
],
"source_item_ids": [
"string"
],
"product_links": {
}
}
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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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",
"wp_status": "publish"
}
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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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"
}
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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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": {
},
"wp_post_id": 0,
"wp_category_ids": [
0
],
"published_url": "string",
"published_at": "string",
"scheduled_at": "string",
"source_item_ids": [
"string"
],
"product_links": {
},
"ai_settings": {
},
"template_id": "string",
"analytics": {
},
"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": {
},
"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": {
},
"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
Format
"binary"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": {
},
"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": {
},
"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": {
}
}
]
}
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"
}
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 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": {
},
"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": {
},
"custom_instructions": "string",
"is_default": false
}
Responses
Successful Response
application/json
JSON
{
"id": "string",
"organization_id": "string",
"name": "string",
"description": "string",
"tone": "string",
"structure": {
},
"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": {
},
"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": {
},
"custom_instructions": "string",
"is_default": true
}
Responses
Successful Response
application/json
JSON
{
"id": "string",
"organization_id": "string",
"name": "string",
"description": "string",
"tone": "string",
"structure": {
},
"custom_instructions": "string",
"is_default": true,
"created_at": "string",
"updated_at": "string"
}