Projects API
POST /api/v1/api/keys
Summary: Create Api Key
Create a new API key for the caller's organization (admin only).
Request Schema (APIKeyCreateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | Human-readable key name |
scopes | array of string | Granted scopes: search, synthesize, chat, admin | |
key_type | string | Credential type: 'secret' (server-side) or 'publishable' (client-safe) | |
description | any | ||
expires_at | any | Optional expiry timestamp | |
rate_limit_per_minute | any | Optional per-minute rate limit |
Response Schema (APIKeyCreateResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | integer | * | |
name | string | * | |
description | any | * | |
key_prefix | string | * | |
scopes | array of string | * | |
key_type | string | * | |
is_active | boolean | * | |
expires_at | any | * | |
last_used_at | any | * | |
created_at | string | * | |
api_key | string | * | Plaintext key — shown only once, store it securely |
GET /api/v1/api/keys
Summary: List Api Keys
List active API keys for the caller's organization (masked).
POST /api/v1/api/keys/tokens
Summary: Mint End User Token
Mint a short-lived delegated end-user JWT (on-behalf-of access).
Requires a secret API key (server-side). The returned token scopes the
session to org_id + external_user_id so a customer's app can call the
public API for its own users without Pragence accounts.
Request Schema (EndUserTokenRequest):
| Property | Type | Required | Description |
|---|---|---|---|
external_user_id | string | * | The calling app's own end-user identifier |
scopes | any | Subset of the key's scopes (defaults to all) | |
ttl_seconds | any | Token lifetime (default 900s) |
Response Schema (EndUserTokenResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
token | string | * | Short-lived delegated end-user JWT |
expires_at | string | * |
DELETE /api/v1/api/keys/{key_id}
Summary: Revoke Api Key
Revoke (deactivate) an API key.
MCP servers
The /api/v1/api/mcp-servers routes, including per-person sign-in, are documented
on MCP servers.
GET /api/v1/branding/themes
Summary: List theme presets
Get all available theme presets for quick branding setup
Response Schema (ThemePresetsResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
presets | array of ThemePreset | * |
POST /api/v1/conversations
Summary: Create Conversation
Create a new conversation.
Supports both registered users and anonymous visitors.
Request Schema (ConversationCreate):
| Property | Type | Required | Description |
|---|---|---|---|
thread_id | any | Custom thread ID (generated if not provided) | |
user_id | any | Registered user ID | |
anonymous_id | any | Anonymous visitor ID | |
visitor_email | any | Visitor email | |
visitor_name | any | ||
visitor_phone | any | ||
visitor_location | any | ||
mode | string | Mode | |
source_url | any | ||
metadata | any |
Response Schema (ConversationResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
thread_id | string | * | |
org_id | string | * | |
project_id | any | * | |
user_id | any | * | |
anonymous_id | any | * | |
visitor_email | any | * | |
visitor_name | any | * | |
visitor_phone | any | * | |
visitor_location | any | * | |
title | any | * | |
summary | any | * | |
mode | string | * | |
status | string | * | |
message_count | integer | * | |
positive_messages | integer | * | |
negative_messages | integer | * | |
overall_sentiment | any | * | |
sentiment_score | any | * | |
detected_tone | any | * | |
topics | object | * | |
tags | array of string | * | |
source_url | any | * | |
metadata | object | * | |
started_at | string | * | |
last_message_at | any | * | |
closed_at | any | * |
GET /api/v1/conversations
Summary: List Conversations
List conversations with filters.
Filters by project, mode, and status.
Response Schema (ConversationListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
conversations | array of ConversationResponse | * | |
total | integer | * | |
limit | integer | * | |
offset | integer | * |
GET /api/v1/conversations/{conversation_id}
Summary: Get Conversation
Get conversation by ID with messages.
Response Schema (ConversationWithMessages - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
thread_id | string | * | |
org_id | string | * | |
project_id | any | * | |
user_id | any | * | |
anonymous_id | any | * | |
visitor_email | any | * | |
visitor_name | any | * | |
visitor_phone | any | * | |
visitor_location | any | * | |
title | any | * | |
summary | any | * | |
mode | string | * | |
status | string | * | |
message_count | integer | * | |
positive_messages | integer | * | |
negative_messages | integer | * | |
overall_sentiment | any | * | |
sentiment_score | any | * | |
detected_tone | any | * | |
topics | object | * | |
tags | array of string | * | |
source_url | any | * | |
metadata | object | * | |
started_at | string | * | |
last_message_at | any | * | |
closed_at | any | * | |
messages | array of MessageResponse | * |
PATCH /api/v1/conversations/{conversation_id}
Summary: Update Conversation
Update conversation metadata.
Request Schema (ConversationUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
title | any | ||
summary | any | ||
status | any | open, closed, archived | |
detected_tone | any | ||
topics | any | ||
tags | any | ||
metadata | any |
Response Schema (ConversationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
thread_id | string | * | |
org_id | string | * | |
project_id | any | * | |
user_id | any | * | |
anonymous_id | any | * | |
visitor_email | any | * | |
visitor_name | any | * | |
visitor_phone | any | * | |
visitor_location | any | * | |
title | any | * | |
summary | any | * | |
mode | string | * | |
status | string | * | |
message_count | integer | * | |
positive_messages | integer | * | |
negative_messages | integer | * | |
overall_sentiment | any | * | |
sentiment_score | any | * | |
detected_tone | any | * | |
topics | object | * | |
tags | array of string | * | |
source_url | any | * | |
metadata | object | * | |
started_at | string | * | |
last_message_at | any | * | |
closed_at | any | * |
POST /api/v1/conversations/{conversation_id}/close
Summary: Close Conversation
Close a conversation.
Response Schema (ConversationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
thread_id | string | * | |
org_id | string | * | |
project_id | any | * | |
user_id | any | * | |
anonymous_id | any | * | |
visitor_email | any | * | |
visitor_name | any | * | |
visitor_phone | any | * | |
visitor_location | any | * | |
title | any | * | |
summary | any | * | |
mode | string | * | |
status | string | * | |
message_count | integer | * | |
positive_messages | integer | * | |
negative_messages | integer | * | |
overall_sentiment | any | * | |
sentiment_score | any | * | |
detected_tone | any | * | |
topics | object | * | |
tags | array of string | * | |
source_url | any | * | |
metadata | object | * | |
started_at | string | * | |
last_message_at | any | * | |
closed_at | any | * |
POST /api/v1/conversations/{conversation_id}/messages
Summary: Add Message
Add a message to a conversation.
Request Schema (MessageCreate):
| Property | Type | Required | Description |
|---|---|---|---|
role | string | * | Message role: user, assistant, system |
content | string | * | Message content |
query_id | any | RAG query ID | |
citations | any | ||
confidence_score | any | ||
latency_ms | any | ||
sentiment | any | positive, negative, neutral | |
sentiment_score | any | ||
source | any | knowledge_base or general_knowledge | |
kb_documents_found | any | ||
metadata | any |
Response Schema (MessageResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
conversation_id | string | * | |
role | string | * | |
content | string | * | |
query_id | any | * | |
citations | array of object | * | |
confidence_score | any | * | |
latency_ms | any | * | |
sentiment | any | * | |
sentiment_score | any | * | |
source | any | * | |
kb_documents_found | any | * | |
feedback | any | * | |
feedback_comment | any | * | |
created_at | string | * | |
metadata | object | * |
GET /api/v1/conversations/{conversation_id}/messages
Summary: Get Messages
Get messages for a conversation.
POST /api/v1/conversations/messages/{message_id}/feedback
Summary: Add Message Feedback
Add feedback to a message.
Request Schema (MessageFeedback):
| Property | Type | Required | Description |
|---|---|---|---|
feedback | string | * | positive or negative |
comment | any |
Response Schema (FeedbackResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
message_id | string | * | |
feedback | string | * | |
comment | any | * | |
created_at | string | * |
POST /api/v1/conversations/messages/{message_id}/regenerate
Summary: Regenerate Message
Regenerate an assistant message by re-executing the query.
This endpoint:
- Finds the user message that preceded this assistant message
- Deletes the current assistant message
- Re-executes the query to generate a new response
- Returns the new assistant message
Request Schema (MessageRegenerateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
collection_id | any | Optional collection filter | |
use_cache | boolean | Whether to use cached results |
Response Schema (MessageRegenerateResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
message_id | string | * | |
conversation_id | string | * | |
content | string | * | |
citations | array of object | * | |
confidence_score | any | * | |
latency_ms | number | * | |
created_at | string | * |
PATCH /api/v1/conversations/messages/{message_id}/edit
Summary: Edit Message
Edit a user message and optionally regenerate the assistant response.
This endpoint:
- Updates the user message content
- If regenerate_response is True:
- Finds and deletes the next assistant message
- Re-executes the query with the new content
- Returns the new assistant message
Request Schema (MessageEditRequest):
| Property | Type | Required | Description |
|---|---|---|---|
content | string | * | New message content |
regenerate_response | boolean | Whether to regenerate the assistant response |
Response Schema (MessageEditResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
message_id | string | * | |
content | string | * | |
updated_at | string | * | |
new_assistant_message | any | New regenerated response if requested |
GET /api/v1/conversations/sitegpt/{conversation_id}/details
Summary: Get Sitegpt Conversation Details
Get detailed conversation view for SiteGPT UI.
Includes chat info, lead info, tickets, and messages.
Response Schema (SiteGPTConversationDetails - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
conversation | ConversationResponse | * | |
chat_info | SiteGPTChatInfo | * | |
lead_info | any | * | |
tickets | array of SiteGPTTicket | * | |
messages | array of MessageResponse | * | |
total_messages | integer | * | |
positive_count | integer | * | |
negative_count | integer | * | |
positive_percentage | number | * | |
negative_percentage | number | * |
GET /api/v1/conversations/inbox
Summary: Get Inbox Conversations
Q5: Admin inbox — list conversations with diagnostics summary.
Returns conversations with a quick summary of the latest assistant message's agent diagnostics (critique score, source, feedback status). Reads from the Conversation model only — no LangGraph state access needed.
Response Schema (InboxConversationListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
conversations | array of InboxConversationListItem | * | |
total | integer | * | |
limit | integer | * | |
offset | integer | * |
GET /api/v1/conversations/inbox/{conversation_id}
Summary: Get Inbox Conversation Detail
Q5: Admin inbox — get conversation detail with agent diagnostics per message.
Returns the full conversation with messages, where each assistant message includes agent diagnostics (critique_score, iterations, source, reformulation_triggered, etc.) captured at write-time.
This reads entirely from the Conversation/Message tables. No LangGraph checkpoint access is needed — diagnostics are captured at write-time via the dual-write pattern (Q2).
Response Schema (InboxConversationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
thread_id | string | * | |
org_id | string | * | |
project_id | any | * | |
user_id | any | * | |
anonymous_id | any | * | |
visitor_email | any | * | |
visitor_name | any | * | |
title | any | * | |
mode | string | * | |
status | string | * | |
message_count | integer | * | |
overall_sentiment | any | * | |
source_url | any | * | |
started_at | string | * | |
last_message_at | any | * | |
messages | array of InboxMessageResponse | * |
POST /api/v1/projects/
Summary: Create Project
Create a new project (organization admin only).
Only organization admins can create new projects.
Request Schema (ProjectCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | Project name |
description | any | Project description | |
config | any | Project-level configuration overrides | |
metadata | any | Additional metadata |
Response Schema (ProjectResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | * | |
org_id | string | * | |
status | string | * | |
visibility | string | ||
config | object | ||
metadata | object | * | |
created_at | string | * | |
updated_at | string | * | |
member_count | any | ||
document_count | any |
GET /api/v1/projects/
Summary: List Projects
List projects the current user has access to.
- Organization admins see all projects in the organization
- Regular users see only projects they are members of
Response Schema (ProjectListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
projects | array of ProjectResponse | * | |
total | integer | * | |
page | integer | * | |
page_size | integer | * |
GET /api/v1/projects/{project_id}
Summary: Get Project
Get project details including members.
User must be a member of the project or an organization admin.
Response Schema (ProjectDetailResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | * | |
org_id | string | * | |
status | string | * | |
visibility | string | ||
config | object | ||
metadata | object | * | |
created_at | string | * | |
updated_at | string | * | |
member_count | any | ||
document_count | any | ||
members | array of ProjectMemberResponse |
PATCH /api/v1/projects/{project_id}
Summary: Update Project
Update project details.
Requires project admin role or organization admin.
Request Schema (ProjectUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | Project name | |
description | any | Project description | |
status | any | Project status: active or archived | |
config | any | Project-level configuration overrides | |
metadata | any | Additional metadata |
Response Schema (ProjectResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | * | |
org_id | string | * | |
status | string | * | |
visibility | string | ||
config | object | ||
metadata | object | * | |
created_at | string | * | |
updated_at | string | * | |
member_count | any | ||
document_count | any |
DELETE /api/v1/projects/{project_id}
Summary: Delete Project
Delete a project (archive it).
Requires project owner role or organization admin. This sets the status to 'archived' rather than hard-deleting.
GET /api/v1/projects/{project_id}/members
Summary: List Project Members
List all members of a project.
User must be a member of the project or an organization admin.
POST /api/v1/projects/{project_id}/members
Summary: Add Project Member
Add a member to a project.
Requires project admin role or organization admin.
Request Schema (ProjectMemberCreate):
| Property | Type | Required | Description |
|---|---|---|---|
user_id | string | * | User ID to add to the project |
role | string | * | Project role: owner, admin, member, or viewer |
Response Schema (ProjectMemberResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
user_id | string | * | |
user_email | any | ||
user_full_name | any | ||
role | string | * | |
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/projects/{project_id}/members/{user_id}
Summary: Update Project Member Role
Update a member's role in a project.
Requires project admin role or organization admin.
Request Schema (ProjectMemberUpdateRole):
| Property | Type | Required | Description |
|---|---|---|---|
role | string | * | New project role: owner, admin, member, or viewer |
Response Schema (ProjectMemberResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
user_id | string | * | |
user_email | any | ||
user_full_name | any | ||
role | string | * | |
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/projects/{project_id}/members/{user_id}
Summary: Remove Project Member
Remove a member from a project.
Requires project admin role or organization admin.
Ingestion and connectors
Ingest, ingestion run and connector routes are documented on their own pages:
Documents (/api/v1/ingest/*),
Ingestion runs (/api/v1/ingestion/*) and
Connectors. The earlier /api/v1/ingestion/jobs*,
/api/v1/ingestion/batch-jobs, /api/v1/ingestion/stats, /api/v1/workflows/* and
/api/v1/ingest/{doc_id}/graph routes have been removed.
GET /api/v1/cache/stats
Summary: Get Cache Stats
Get cache statistics.
Returns hit rate, total requests, and cache status.
POST /api/v1/cache/clear
Summary: Clear Cache
Clear all cache entries.
Requires admin role and confirmation. Use with caution in production!
Request Schema (CacheClearRequest):
| Property | Type | Required | Description |
|---|---|---|---|
confirm | boolean | * | Must be true to confirm cache clear |
POST /api/v1/cache/invalidate/{doc_id}
Summary: Invalidate Document Cache
Invalidate cache entries for a specific document.
Call this when a document is updated or deleted.
GET /api/v1/multimodal/images/{image_id}
Summary: Get Image
Get image binary data.
Returns the image file with appropriate content type.
GET /api/v1/dashboard/stats
Summary: Get Dashboard Stats
Get dashboard statistics for the current user's organization.
Returns:
- Total documents, queries, projects
- Storage usage
- Growth percentages (compared to last month)
Response Schema (DashboardStats - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
total_documents | integer | * | |
total_queries | integer | * | |
total_projects | integer | * | |
storage_used_bytes | integer | * | |
documents_growth | number | * | |
queries_growth | number | * | |
projects_growth | number | * |
GET /api/v1/dashboard/activity
Summary: Get Recent Activity
Get recent activity for the current user's organization.
Args: limit: Maximum number of activity items to return (default: 10)
Returns: List of recent activity items with descriptions and timestamps
POST /api/v1/ip-whitelist/entries
Summary: Add Ip Entry
Add an IP address or CIDR range to the organization's whitelist.
Only organization admins can add IP entries.
- ip_address: Single IP (192.168.1.1) or CIDR range (192.168.1.0/24)
- description: Optional description
- expires_at: Optional expiration date
Request Schema (IPAddRequest):
| Property | Type | Required | Description |
|---|---|---|---|
ip_address | string | * | IP address or CIDR range (e.g., '192.168.1.1' or '192.168.1.0/24') |
description | any | Optional description for this IP entry | |
expires_at | any | Optional expiration date for this entry |
Response Schema (IPWhitelistEntry - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
ip_address | string | * | |
ip_range_start | any | ||
ip_range_end | any | ||
description | any | ||
is_active | boolean | * | |
created_at | string | * | |
created_by_user_id | any | ||
expires_at | any |
GET /api/v1/ip-whitelist/entries
Summary: List Ip Entries
List all IP whitelist entries for the organization.
Only organization admins can view IP entries.
- include_inactive: Include disabled entries
- include_expired: Include expired entries
Response Schema (IPWhitelistResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
entries | array of IPWhitelistEntry | * | |
total | integer | * |
GET /api/v1/ip-whitelist/entries/{entry_id}
Summary: Get Ip Entry
Get a specific IP whitelist entry.
Only organization admins can view IP entries.
Response Schema (IPWhitelistEntry - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
ip_address | string | * | |
ip_range_start | any | ||
ip_range_end | any | ||
description | any | ||
is_active | boolean | * | |
created_at | string | * | |
created_by_user_id | any | ||
expires_at | any |
PATCH /api/v1/ip-whitelist/entries/{entry_id}
Summary: Update Ip Entry
Update an IP whitelist entry.
Only organization admins can update IP entries.
- description: New description
- is_active: Enable/disable the entry
- expires_at: New expiration date
Request Schema (IPUpdateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
description | any | New description for this entry | |
is_active | any | Enable or disable this entry | |
expires_at | any | New expiration date |
Response Schema (IPWhitelistEntry - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
ip_address | string | * | |
ip_range_start | any | ||
ip_range_end | any | ||
description | any | ||
is_active | boolean | * | |
created_at | string | * | |
created_by_user_id | any | ||
expires_at | any |
DELETE /api/v1/ip-whitelist/entries/{entry_id}
Summary: Delete Ip Entry
Delete an IP whitelist entry.
Only organization admins can delete IP entries.
GET /api/v1/ip-whitelist/status
Summary: Get Whitelist Status
Get IP whitelist status for the organization.
Returns whether whitelisting is enabled and entry statistics.
Response Schema (IPWhitelistStatusResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
enabled | boolean | * | |
total_entries | integer | * | |
active_entries | integer | * | |
expired_entries | integer | * |
PUT /api/v1/ip-whitelist/settings
Summary: Update Whitelist Settings
Enable or disable IP whitelisting for the organization.
WARNING: Enabling IP whitelisting without any entries will block all access! Make sure to add your IP addresses before enabling.
Request Schema (IPWhitelistSettingRequest):
| Property | Type | Required | Description |
|---|---|---|---|
enabled | boolean | * | Whether to enable IP whitelisting for the organization |
Response Schema (IPWhitelistStatusResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
enabled | boolean | * | |
total_entries | integer | * | |
active_entries | integer | * | |
expired_entries | integer | * |
GET /api/v1/ip-whitelist/check/my-ip
Summary: Check My Ip
Check if your current IP address is whitelisted.
Useful for users to verify their IP before an admin enables whitelisting.
Response Schema (IPCheckResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
ip_address | string | * | |
is_whitelisted | boolean | * | |
message | string | * |
POST /api/v1/ip-whitelist/check
Summary: Check Ip
Check if a specific IP address would be whitelisted.
Only organization admins can check arbitrary IPs. Useful for testing before adding entries.
Request Schema (IPCheckRequest):
| Property | Type | Required | Description |
|---|---|---|---|
ip_address | string | * | IP address to check |
Response Schema (IPCheckResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
ip_address | string | * | |
is_whitelisted | boolean | * | |
message | string | * |
POST /api/v1/synthesize
Summary: Synthesize
Stateless RAG endpoint: retrieval + fusion + rerank + LLM answer generation.
This endpoint performs single-turn question answering by:
- Retrieval: Search using hybrid retrieval (vector + BM25)
- Fusion: Merge results using Reciprocal Rank Fusion (RRF)
- Reranking: Rerank top candidates with CrossEncoder
- Generation: Generate answer with LLM and citations
Use cases:
- Help centers and FAQ systems
- Programmatic Q&A endpoints
- Single-turn question answering
- Applications that need answers without conversation state
Features:
- Stateless (no conversation history)
- Configurable LLM model and parameters
- Custom prompt templates
- Citation styles (inline, footnote, none)
- Token usage tracking and cost estimation
- Detailed retrieval and answer metadata
Performance:
- Typical latency: 8-12 seconds
- Retrieval: ~4-5 seconds
- Reranking: ~3-4 seconds
- Answer generation: ~1-2 seconds
Rate limits:
- 20 requests/minute per API key
Args: request: Synthesis request with query and configuration current_user: Authenticated user (JWT)
Returns: Synthesis response with answer, sources, and metadata
Raises: HTTPException: 400 if invalid request, 401 if unauthorized
Request Schema (SynthesizeRequest):
| Property | Type | Required | Description |
|---|---|---|---|
query | string | * | Question or query |
search_modes | any | Search modes to use for retrieval | |
top_k_per_mode | integer | Results per mode before fusion | |
top_k_for_rerank | integer | Top candidates to rerank with CrossEncoder | |
final_k | integer | Final number of chunks to use for answer generation | |
filters | any | Structured filter clauses | |
collection_id | any | Filter to specific collection | |
project_id | any | Filter to specific project | |
fusion_config | any | RRF fusion config (e.g., {'k': 60}) | |
llm_model | any | LLM model to use (defaults to settings) | |
prompt_template | any | Custom prompt template (use {context} and {query} placeholders) | |
temperature | number | LLM temperature | |
max_tokens | any | Max tokens for answer | |
include_citations | boolean | Include source citations | |
citation_style | string | Citation style: 'inline', 'footnote', or 'none' |
Response Schema (SynthesizeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
query_received | string | * | Query as received |
answer | string | * | Generated answer |
answer_metadata | AnswerMetadata | * | Answer generation metadata |
sources | array of AnswerSource | * | Source documents used |
retrieval_metadata | RetrievalMetadata | * | Retrieval process metadata |
request_id | string | * | Unique request ID |
GET /api/v1/guardrails/status
Summary: Get Guardrails Status
Get the current status of guardrails service.
Returns configuration and initialization state.
Response Schema (GuardrailsStatusResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
enabled | boolean | * | |
initialized | boolean | * | |
config_path | string | * | |
input_rails_enabled | boolean | * | |
output_rails_enabled | boolean | * | |
features | object | * |
POST /api/v1/guardrails/check-input
Summary: Check Input
Test input text against input guardrails.
Useful for testing what kinds of inputs would be blocked.
Request Schema (CheckInputRequest):
| Property | Type | Required | Description |
|---|---|---|---|
text | string | * | |
context | any |
Response Schema (GuardrailCheckResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
action | string | * | |
is_blocked | boolean | * | |
is_allowed | boolean | * | |
original_text | string | * | |
modified_text | any | ||
reason | any | ||
rail_triggered | any | ||
confidence | number |
POST /api/v1/guardrails/check-output
Summary: Check Output
Test output text against output guardrails.
Useful for testing what kinds of outputs would be blocked or modified.
Request Schema (CheckOutputRequest):
| Property | Type | Required | Description |
|---|---|---|---|
response | string | * | |
user_input | string | * | |
context | any |
Response Schema (GuardrailCheckResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
action | string | * | |
is_blocked | boolean | * | |
is_allowed | boolean | * | |
original_text | string | * | |
modified_text | any | ||
reason | any | ||
rail_triggered | any | ||
confidence | number |
POST /api/v1/guardrails/initialize
Summary: Initialize Guardrails
Manually initialize or reinitialize guardrails service.
Admin only - useful for reloading configuration.
GET /api/v1/guardrails/test-patterns
Summary: Get Test Patterns
Get example test patterns for guardrails testing.
Provides sample inputs that should trigger various rails.
POST /api/v1/admin/playground/benchmark
Summary: Run Benchmark
Run benchmark across multiple queries.
Admin only - Benchmark search/chat quality across a query set.
Credits: Charged per query executed:
- Search mode: 1 credit per query
- Chat mode: 1-2 credits per query (2 if reformulation triggered)
Features:
- Batch execution of multiple queries
- Latency statistics (avg, p50, p95, min, max)
- Quality metrics (avg top score, low score detection)
- Gap summary across all queries
Use this to:
- Evaluate overall retrieval quality
- Identify systematic gaps in coverage
- Benchmark performance characteristics
- Generate quality reports
Request Schema (BenchmarkRequest):
| Property | Type | Required | Description |
|---|---|---|---|
queries | array of string | * | List of queries to benchmark |
collection_id | any | Filter to specific collection | |
mode | PlaygroundMode | Benchmark mode (search or chat) |
Response Schema (BenchmarkResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
total_queries | integer | * | |
successful | integer | * | |
failed | integer | * | |
avg_latency_ms | number | * | |
p50_latency_ms | number | * | |
p95_latency_ms | number | * | |
min_latency_ms | number | * | |
max_latency_ms | number | * | |
avg_top_score | any | ||
queries_with_low_scores | integer | Queries with top score < 0.5 | |
results | array of BenchmarkResult | * | |
gap_summary | object | Summary of identified gaps | |
request_id | string | * | |
credits_used | any | Total credits consumed by benchmark | |
credits_remaining | any | Remaining credit balance |
POST /api/v1/projects/{project_id}/from-template
Summary: Set up a project from a marketplace template
Request Schema (ActivateTemplateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
template_id | string | * | Marketplace template id, e.g. 'T1' |
POST /api/v1/projects/{project_id}/verticals
Summary: Activate a vertical for a project
Request Schema (ActivateVerticalRequest):
| Property | Type | Required | Description |
|---|---|---|---|
vertical_key | string | * | Registered vertical key, e.g. higher_ed or general |
DELETE /api/v1/projects/{project_id}/verticals/{vertical_key}
Summary: Deactivate a vertical
GET /api/v1/projects/{project_id}/channels
Summary: List channels
POST /api/v1/projects/{project_id}/channels
Summary: Create Channel
Request Schema (ChannelCreateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
type | string | * | widget |
config | object | ||
target_agent_key | any | Pin to one agent; NULL = project entry point |
Response Schema (ChannelResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
project_id | string | * | |
type | string | * | |
config | object | ||
target_agent_key | any | ||
enabled | boolean | * |
GET /api/v1/onboarding/status
Summary: First-run onboarding state for the current org
Report whether the org still needs onboarding and where its default project is.
needs_onboarding is true until the wizard is completed (stored on the org).
default_project_id / has_agents let the wizard deep-link straight to a
working chat (the starter project is auto-provisioned at registration).
POST /api/v1/onboarding/complete
Summary: Mark the current org's onboarding as complete
Set the org's onboarded flag so the first-run wizard stops appearing.
POST /api/v1/widgets
Summary: Create Widget
Create a new widget configuration.
Creates a widget that can be embedded on external websites. Each widget has a unique key used in the embed snippet.
Request Schema (WidgetConfigCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
description | any | ||
primary_color | string | ||
text_color | string | ||
position | string | ||
avatar_url | any | ||
logo_url | any | ||
powered_by | boolean | ||
greeting | string | ||
placeholder | string | ||
auto_open | boolean | ||
auto_open_delay | integer | ||
features | object | ||
allowed_domains | array of string | ||
rate_limit_messages | integer | ||
rate_limit_window | integer | ||
collection_id | any | ||
system_prompt | any | ||
project_id | any |
Response Schema (WidgetConfigResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
description | any | ||
primary_color | string | ||
text_color | string | ||
position | string | ||
avatar_url | any | ||
logo_url | any | ||
powered_by | boolean | ||
greeting | string | ||
placeholder | string | ||
auto_open | boolean | ||
auto_open_delay | integer | ||
features | object | ||
allowed_domains | array of string | ||
rate_limit_messages | integer | ||
rate_limit_window | integer | ||
collection_id | any | ||
system_prompt | any | ||
id | string | * | |
org_id | string | * | |
project_id | any | ||
widget_key | string | * | |
is_active | boolean | * | |
total_conversations | integer | * | |
total_messages | integer | * | |
created_at | string | * | |
updated_at | string | * |
GET /api/v1/widgets
Summary: List Widgets
List widget configurations.
Returns all widgets for the current organization.
Response Schema (WidgetConfigListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
items | array of WidgetConfigResponse | * | |
total | integer | * |
GET /api/v1/widgets/{widget_id}
Summary: Get Widget
Get a widget configuration by ID.
Response Schema (WidgetConfigResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
description | any | ||
primary_color | string | ||
text_color | string | ||
position | string | ||
avatar_url | any | ||
logo_url | any | ||
powered_by | boolean | ||
greeting | string | ||
placeholder | string | ||
auto_open | boolean | ||
auto_open_delay | integer | ||
features | object | ||
allowed_domains | array of string | ||
rate_limit_messages | integer | ||
rate_limit_window | integer | ||
collection_id | any | ||
system_prompt | any | ||
id | string | * | |
org_id | string | * | |
project_id | any | ||
widget_key | string | * | |
is_active | boolean | * | |
total_conversations | integer | * | |
total_messages | integer | * | |
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/widgets/{widget_id}
Summary: Update Widget
Update a widget configuration.
Request Schema (WidgetConfigUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | ||
description | any | ||
primary_color | any | ||
text_color | any | ||
position | any | ||
avatar_url | any | ||
logo_url | any | ||
powered_by | any | ||
greeting | any | ||
placeholder | any | ||
auto_open | any | ||
auto_open_delay | any | ||
features | any | ||
allowed_domains | any | ||
rate_limit_messages | any | ||
rate_limit_window | any | ||
collection_id | any | ||
system_prompt | any | ||
is_active | any |
Response Schema (WidgetConfigResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
description | any | ||
primary_color | string | ||
text_color | string | ||
position | string | ||
avatar_url | any | ||
logo_url | any | ||
powered_by | boolean | ||
greeting | string | ||
placeholder | string | ||
auto_open | boolean | ||
auto_open_delay | integer | ||
features | object | ||
allowed_domains | array of string | ||
rate_limit_messages | integer | ||
rate_limit_window | integer | ||
collection_id | any | ||
system_prompt | any | ||
id | string | * | |
org_id | string | * | |
project_id | any | ||
widget_key | string | * | |
is_active | boolean | * | |
total_conversations | integer | * | |
total_messages | integer | * | |
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/widgets/{widget_id}
Summary: Delete Widget
Delete a widget configuration.
POST /api/v1/widgets/{widget_id}/regenerate-key
Summary: Regenerate Widget Key
Regenerate the widget's public key.
This will invalidate the current embed code. All existing embeds will need to be updated with the new key.
GET /api/v1/widgets/{widget_id}/embed-code
Summary: Get Embed Code
Get the embed code for a widget.
Response Schema (WidgetEmbedCodeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
widget_key | string | * | |
embed_code | string | * | |
cdn_url | string | * |
POST /api/v1/widget/init
Summary: Init Widget
Initialize a widget session.
This is called when the widget loads on a page. It validates the widget key, checks domain restrictions, and creates a session.
Returns the widget configuration and a session token for subsequent requests.
Request Schema (WidgetInitRequest):
| Property | Type | Required | Description |
|---|---|---|---|
url | any | ||
referrer | any | ||
user_agent | any | ||
session_token | any | Previous session token from localStorage for cross-visit persistence | |
new_conversation | boolean | Start a new conversation even if resuming an existing session | |
user_token | any | Optional JWT token to link widget session to an authenticated user |
Response Schema (WidgetInitResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | ||
config | WidgetInitConfigResponse | * | |
session_id | string | * | |
conversation_id | any | Active conversation ID (if resuming a session with an existing conversation) | |
is_resumed | boolean | Whether this is a resumed session (True) or new session (False) | |
session_expires_at | any | ISO timestamp when the session expires (for client-side TTL management) |
POST /api/v1/widget/conversations/new
Summary: Start New Conversation
Q3: Start a new conversation on the current session.
This clears the session's conversation link so the next message creates a fresh conversation. The previous conversation remains accessible via its ID for history viewing.
POST /api/v1/widget/messages
Summary: Send Message
Send a message and get a response.
This is the main chat endpoint. It sends the user's message to the RAG system and returns the assistant's response.
Request Schema (WidgetMessageRequest):
| Property | Type | Required | Description |
|---|---|---|---|
content | string | * | |
conversation_id | any | ||
attachments | any |
Response Schema (WidgetSendMessageResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | ||
message | WidgetMessageResponse | * | |
conversation_id | string | * |
POST /api/v1/widget/messages/stream
Summary: Stream Message
Send a message and stream the response.
Returns a Server-Sent Events stream with:
- conversation_id: The conversation ID
- content: Streamed content chunks
- done: Final message with citations
Request Schema (WidgetMessageRequest):
| Property | Type | Required | Description |
|---|---|---|---|
content | string | * | |
conversation_id | any | ||
attachments | any |
GET /api/v1/widget/conversations/{conversation_id}
Summary: Get Conversation
Get conversation history.
Response Schema (WidgetConversationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
messages | array of WidgetMessageResponse | * | |
created_at | string | * | |
updated_at | string | * |
POST /api/v1/widget/messages/{message_id}/feedback
Summary: Submit Feedback
Submit feedback for a message.
Request Schema (WidgetFeedbackRequest):
| Property | Type | Required | Description |
|---|---|---|---|
feedback | string | * | |
comment | any |
POST /api/v1/widget/attachments
Summary: Upload Attachments
Upload file attachments for a message.
Accepts multiple files up to 10MB each. Supported types: images (JPEG, PNG, GIF, WebP), PDF, TXT, DOC, DOCX.
Returns list of attachment metadata with URLs for subsequent message.
GET /health
Summary: Health Check
Check system health.
Returns health status of all components including database, cache, and other services.
Response Schema (HealthCheckResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
status | string | * | |
timestamp | string | ||
components | array of ComponentHealth | * | |
version | string |
GET /health/ready
Summary: Readiness Check
Kubernetes readiness probe endpoint.
Returns 200 if service is ready to accept traffic.
GET /health/live
Summary: Liveness Check
Kubernetes liveness probe endpoint.
Returns 200 if service is alive (doesn't check dependencies).
GET /public/config
Summary: Public Deployment Config
Public deployment configuration the admin web console reads at boot.
No auth — returns only non-sensitive deployment flags so the SPA can gate
itself when the admin UI is not licensed (self-hosted) and adapt to the
deployment mode. admin_ui_enabled is the license lever (see
Settings.admin_ui_enabled).
GET /webhooks/whatsapp
Summary: Verify Subscription
Meta subscription handshake — echo the challenge when the verify token matches.
POST /webhooks/whatsapp
Summary: Inbound
Receive inbound WhatsApp messages (HMAC-verified) and reply via the project agent.
GET /api/v1/artifacts/{artifact_id}
Summary: Get artifact metadata
GET /api/v1/artifacts/{artifact_id}/download
Summary: Download the artifact file
GET /api/v1/artifacts/{artifact_id}/raw
Summary: View the artifact inline (e.g. HTML preview)
GET /api/v1/actions
Summary: List available actions
GET /api/v1/actions/pending/{thread_id}
Summary: Get action(s) awaiting approval for a thread
POST /api/v1/actions/confirm
Summary: Approve or reject pending action(s)
Request Schema (ActionConfirmRequest):
| Property | Type | Required | Description |
|---|---|---|---|
thread_id | string | * | Conversation thread paused for action approval |
approved | boolean | * | Approve (execute) or reject (cancel) the proposed action(s) |
mode | any | Mode, if the query used a product workflow | |
org_id | any | Organization id, if the query used a product workflow |
GET /api/v1/bot
Summary: Get agent info
Get public info about the organization's entry agent.
Returns the agent display name, greeting, and suggested questions. Used by the widget/frontend to initialize the chat UI. No authentication required.
Response Schema (BotInfoResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
greeting | string | * | |
suggested_questions | array of string | ||
vertical_type | any | ||
is_active | boolean |
GET /api/v1/bot/config
Summary: Get resolved agent config
Get the resolved config for the organization's entry agent.
GET /api/v1/portal/config
Summary: Get Portal Config
One public call the portal makes on load to bootstrap a tenant.
Response Schema (PortalConfigResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
organization | object | * | |
branding | object | * | |
agent | object | * | |
publishable_key | any | * |
GET /api/v1/credits/balance
Summary: Get Credit Balance
Get current organization's credit balance.
Returns balance details including subscription and purchased credits.
Response Schema (CreditBalanceResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
plan_id | any | * | |
plan_name | any | * | |
plan_display_name | any | * | |
current_balance | integer | * | |
subscription_credits | integer | * | |
purchased_credits | integer | * | |
billing_cycle_start | any | * | |
billing_cycle_end | any | * | |
lifetime_credits_used | integer | * | |
lifetime_credits_purchased | integer | * | |
created_at | string | * | |
updated_at | string | * |
GET /api/v1/credits/check/{action_type}
Summary: Check Credits
Check if organization has sufficient credits for an action.
Does not deduct credits, only checks availability.
Response Schema (CreditCheckResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
has_sufficient | boolean | * | |
required | integer | * | |
available | integer | * | |
action | string | * |
GET /api/v1/credits/plans
Summary: List Plans
List available subscription plans.
Public endpoint - no authentication required.
Response Schema (CreditPlanListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
plans | array of CreditPlanResponse | * |
POST /api/v1/credits/plan
Summary: Change Plan
Change organization's subscription plan (admin only).
Note: Credits are adjusted on next billing cycle renewal.
Request Schema (ChangePlanRequest):
| Property | Type | Required | Description |
|---|---|---|---|
plan_name | string | * | Name of the new plan |
Response Schema (ChangePlanResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | * | |
previous_plan | any | * | |
new_plan | string | * | |
message | string | * | |
balance | CreditBalanceResponse | * |
GET /api/v1/credits/pricing
Summary: List Pricing
List credit pricing for all action types.
Public endpoint - no authentication required.
Response Schema (PricingListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
pricing | array of CreditPricingResponse | * |
GET /api/v1/credits/transactions
Summary: List Transactions
Get organization's credit transaction history.
Supports filtering by transaction type, action type, and date range.
Response Schema (TransactionListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
transactions | array of CreditTransactionResponse | * | |
total | integer | * | |
page | integer | * | |
page_size | integer | * |
GET /api/v1/credits/usage
Summary: Get Usage Summary
Get credit usage summary for organization.
Returns breakdown by action type for the specified period.
Response Schema (UsageSummaryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
period_start | string | * | |
period_end | string | * | |
total_used | integer | * | |
by_action | object | * | |
current_balance | integer | * | |
subscription_credits | integer | * | |
purchased_credits | integer | * |
POST /api/v1/credits/purchase
Summary: Create Purchase
Create a credit purchase order (admin only).
Returns purchase record with pending status. Call /credits/purchase/{id}/complete after payment succeeds.
Request Schema (CreditPurchaseRequest):
| Property | Type | Required | Description |
|---|---|---|---|
credits_amount | integer | * | Number of credits to purchase (min 100) |
payment_provider | any | Payment provider (stripe, paystack) |
Response Schema (CreditPurchaseResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
user_id | any | * | |
credits_amount | integer | * | |
price_cents | integer | * | |
currency | string | * | |
payment_provider | any | * | |
payment_id | any | * | |
payment_method | any | * | |
status | string | * | |
completed_at | any | * | |
refunded_at | any | * | |
created_at | string | * |
POST /api/v1/credits/purchase/{purchase_id}/complete
Summary: Complete Purchase
Complete a pending purchase and add credits (admin only).
Called after payment provider confirms payment.
Request Schema (CompletePurchaseRequest):
| Property | Type | Required | Description |
|---|---|---|---|
payment_id | string | * | External payment reference ID |
payment_method | any | Payment method used |
Response Schema (CreditPurchaseResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
user_id | any | * | |
credits_amount | integer | * | |
price_cents | integer | * | |
currency | string | * | |
payment_provider | any | * | |
payment_id | any | * | |
payment_method | any | * | |
status | string | * | |
completed_at | any | * | |
refunded_at | any | * | |
created_at | string | * |
GET /api/v1/credits/purchases
Summary: List Purchases
List organization's credit purchases (admin only).
Response Schema (PurchaseListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
purchases | array of CreditPurchaseResponse | * | |
total | integer | * | |
page | integer | * | |
page_size | integer | * |
GET /api/v1/credits/packages
Summary: List Credit Packages
List available credit packages for purchase.
Returns pricing for all available credit amounts. Public endpoint - no authentication required.
POST /api/v1/credits/checkout
Summary: Create Checkout
Create a Stripe checkout session for credit purchase (admin only).
Returns a URL to redirect the user to Stripe's hosted checkout page. After payment, Stripe will redirect to success_url with session_id parameter.
GET /api/v1/credits/checkout/{session_id}
Summary: Get Checkout Status
Get the status of a checkout session.
Use this after redirect from Stripe to verify payment status.
POST /api/v1/credits/admin/adjust
Summary: Admin Adjust Credits
Manually adjust credits for an organization (admin only).
Use positive amount to add credits, negative to remove.
Request Schema (AdminCreditAdjustment):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | Organization ID |
amount | integer | * | Credits to add (positive) or remove (negative) |
reason | string | * | Reason for adjustment |
Response Schema (AdminCreditAdjustmentResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | * | |
transaction_id | string | * | |
org_id | string | * | |
amount | integer | * | |
new_balance | integer | * | |
reason | string | * |
POST /api/v1/credits/admin/renew-all
Summary: Trigger Subscription Renewals
Trigger subscription renewal for all expired billing cycles (admin only).
This endpoint runs the renewal flow synchronously and returns results. For production, use the scheduled Prefect flow instead.
POST /api/v1/credits/admin/renew/{org_id}
Summary: Renew Org Subscription
Renew subscription for a specific organization (admin only).
Useful for manual renewals or customer support actions.
GET /api/v1/credits/admin/low-balance
Summary: Check Low Balances
Check for organizations with low credit balances (admin only).
Returns list of orgs whose balance is below the threshold percentage of their monthly credit allowance.
GET /api/v1/credits/admin/expiring
Summary: List Expiring Subscriptions
List subscriptions expiring soon (admin only).
Shows organizations whose billing cycle ends within the specified days.
POST /api/v1/credits/admin/alerts/low-balance
Summary: Trigger Low Balance Alerts
Trigger low balance alert check and notifications (admin only).
Sends email notifications to org admins whose balance is below threshold.
POST /api/v1/credits/admin/alerts/exhausted
Summary: Trigger Exhausted Alerts
Trigger credit exhaustion alerts (admin only).
Sends alerts to organizations with zero credits.
POST /api/v1/credits/admin/alerts/test
Summary: Send Test Alert
Send a test alert notification (admin only).
Useful for verifying email/webhook configuration.
POST /webhooks/stripe
Summary: Stripe Webhook
Handle Stripe webhook events.
This endpoint receives events from Stripe for:
- checkout.session.completed (credit purchase completed)
- payment_intent.succeeded (payment confirmed)
- payment_intent.payment_failed (payment failed)
- charge.refunded (refund processed)
- customer.subscription.* (subscription events)
- invoice.paid (subscription renewal)
Configure webhook URL in Stripe Dashboard: https://dashboard.stripe.com/webhooks
Required events to enable:
- checkout.session.completed
- payment_intent.succeeded
- payment_intent.payment_failed
- charge.refunded
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.paid
- invoice.payment_failed
POST /webhooks/paystack
Summary: Paystack Webhook
Handle Paystack webhook events (for African markets).
Similar to Stripe but for Paystack payment provider. Enable with ENABLE_PAYSTACK=true in configuration.
GET /api/v1/cms/schema/field-types
Summary: List Field Types
List all available field types.
GET /api/v1/cms/schema/field-types/{slug}
Summary: Get Field Type
Get a field type by slug.
Response Schema (FieldTypeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
slug | string | * | |
name | string | * | |
description | any | ||
category | string | * | |
input_schema | object | * | |
output_schema | object | * | |
default_settings | object | ||
editor_component | string | * | |
display_component | string | * | |
list_component | any | ||
is_localizable | boolean | ||
is_searchable | boolean | ||
is_sortable | boolean | ||
is_filterable | boolean | ||
is_system | boolean | ||
is_enabled | boolean |
GET /api/v1/cms/schema/validation-rules
Summary: List Validation Rules
List validation rules, optionally filtered by field type.
GET /api/v1/cms/schema/content-types
Summary: List Content Types
List content types for the organization.
Omit project_id for the org-level view (every type). Pass a project id for
that project's Content tab (project-private types ∪ org-shared types).
POST /api/v1/cms/schema/content-types
Summary: Create Content Type
Create a new content type (org-shared or project-private).
Request Schema (ContentTypeCreate):
| Property | Type | Required | Description |
|---|---|---|---|
slug | string | * | URL-safe identifier |
name | string | * | Singular display name |
name_plural | string | * | Plural display name |
project_id | any | Scope: project this type is private to. Omit/null = org-shared (all projects). Set at creation only. | |
description | any | ||
icon | any | ||
display_field | string | * | Field api_id to use as entry title |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
sort_order | integer | ||
fields | array of FieldDefinitionCreate |
Response Schema (ContentTypeResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
project_id | any | ||
slug | string | * | |
name | string | * | |
name_plural | string | * | |
description | any | ||
icon | any | ||
display_field | string | * | |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
is_system | boolean | ||
is_enabled | boolean | ||
sort_order | integer | ||
fields | array of FieldDefinitionResponse | ||
created_at | string | * | |
updated_at | string | * |
GET /api/v1/cms/schema/content-types/{slug}
Summary: Get Content Type
Get a content type by slug.
Response Schema (ContentTypeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
project_id | any | ||
slug | string | * | |
name | string | * | |
name_plural | string | * | |
description | any | ||
icon | any | ||
display_field | string | * | |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
is_system | boolean | ||
is_enabled | boolean | ||
sort_order | integer | ||
fields | array of FieldDefinitionResponse | ||
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/cms/schema/content-types/{slug}
Summary: Update Content Type
Update a content type.
Request Schema (ContentTypeUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | ||
name_plural | any | ||
description | any | ||
icon | any | ||
display_field | any | ||
preview_fields | any | ||
is_singleton | any | ||
enable_versioning | any | ||
enable_localization | any | ||
enable_slug | any | ||
enable_scheduling | any | ||
workflow_id | any | ||
api_enabled | any | ||
api_cache_ttl | any | ||
rag_enabled | any | ||
rag_template | any | ||
sort_order | any | ||
is_enabled | any |
Response Schema (ContentTypeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
project_id | any | ||
slug | string | * | |
name | string | * | |
name_plural | string | * | |
description | any | ||
icon | any | ||
display_field | string | * | |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
is_system | boolean | ||
is_enabled | boolean | ||
sort_order | integer | ||
fields | array of FieldDefinitionResponse | ||
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/schema/content-types/{slug}
Summary: Delete Content Type
Delete a content type.
POST /api/v1/cms/schema/content-types/{slug}/fields
Summary: Add Field
Add a field to a content type.
Request Schema (FieldDefinitionCreate):
| Property | Type | Required | Description |
|---|---|---|---|
api_id | string | * | API field name |
name | string | * | Human-readable label |
description | any | ||
placeholder | any | ||
field_type_slug | string | * | Field type slug |
settings | object | ||
validation_rules | array of object | Array of {rule_slug, config} | |
is_required | boolean | ||
is_unique | boolean | ||
is_localizable | boolean | ||
ui_width | string | Grid width: full, half, third, quarter | |
ui_group | any | ||
ui_order | integer | ||
ui_hidden | boolean | ||
ui_readonly | boolean | ||
conditions | any | ||
default_value | any |
Response Schema (ContentTypeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
project_id | any | ||
slug | string | * | |
name | string | * | |
name_plural | string | * | |
description | any | ||
icon | any | ||
display_field | string | * | |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
is_system | boolean | ||
is_enabled | boolean | ||
sort_order | integer | ||
fields | array of FieldDefinitionResponse | ||
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/cms/schema/content-types/{slug}/fields/{api_id}
Summary: Update Field
Update a field definition.
Request Schema (FieldDefinitionUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | ||
description | any | ||
placeholder | any | ||
settings | any | ||
validation_rules | any | ||
is_required | any | ||
is_unique | any | ||
is_localizable | any | ||
ui_width | any | ||
ui_group | any | ||
ui_order | any | ||
ui_hidden | any | ||
ui_readonly | any | ||
conditions | any | ||
default_value | any |
Response Schema (ContentTypeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
project_id | any | ||
slug | string | * | |
name | string | * | |
name_plural | string | * | |
description | any | ||
icon | any | ||
display_field | string | * | |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
is_system | boolean | ||
is_enabled | boolean | ||
sort_order | integer | ||
fields | array of FieldDefinitionResponse | ||
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/schema/content-types/{slug}/fields/{api_id}
Summary: Delete Field
Delete a field from a content type.
Response Schema (ContentTypeResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
project_id | any | ||
slug | string | * | |
name | string | * | |
name_plural | string | * | |
description | any | ||
icon | any | ||
display_field | string | * | |
preview_fields | array of string | ||
is_singleton | boolean | ||
enable_versioning | boolean | ||
enable_localization | boolean | ||
enable_slug | boolean | ||
enable_scheduling | boolean | ||
workflow_id | any | ||
api_enabled | boolean | ||
api_cache_ttl | integer | ||
rag_enabled | boolean | ||
rag_template | any | ||
is_system | boolean | ||
is_enabled | boolean | ||
sort_order | integer | ||
fields | array of FieldDefinitionResponse | ||
created_at | string | * | |
updated_at | string | * |
POST /api/v1/cms/schema/import
Summary: Import Schema
Import schema from YAML/JSON file.
GET /api/v1/cms/schema/export
Summary: Export Schema
Export schema as JSON.
GET /api/v1/cms/schema/workflows
Summary: List Workflows
List all workflows for the organization.
POST /api/v1/cms/schema/workflows
Summary: Create Workflow
Create a new workflow.
Request Schema (WorkflowCreate):
| Property | Type | Required | Description |
|---|---|---|---|
slug | string | * | |
name | string | * | |
description | any | ||
initial_state | string | * | State slug for new entries |
states | array of WorkflowStateCreate | ||
transitions | array of WorkflowTransitionCreate |
Response Schema (apps__cms__schemas__workflow__WorkflowResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
slug | string | * | |
name | string | * | |
description | any | ||
initial_state | string | * | |
is_system | boolean | ||
is_enabled | boolean | ||
states | array of WorkflowStateResponse | ||
transitions | array of WorkflowTransitionResponse | ||
created_at | string | * | |
updated_at | string | * |
GET /api/v1/cms/schema/workflows/{slug}
Summary: Get Workflow
Get a workflow by slug.
Response Schema (apps__cms__schemas__workflow__WorkflowResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
slug | string | * | |
name | string | * | |
description | any | ||
initial_state | string | * | |
is_system | boolean | ||
is_enabled | boolean | ||
states | array of WorkflowStateResponse | ||
transitions | array of WorkflowTransitionResponse | ||
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/cms/schema/workflows/{slug}
Summary: Update Workflow
Update a workflow.
Request Schema (WorkflowUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | ||
description | any | ||
initial_state | any | ||
is_enabled | any |
Response Schema (apps__cms__schemas__workflow__WorkflowResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
slug | string | * | |
name | string | * | |
description | any | ||
initial_state | string | * | |
is_system | boolean | ||
is_enabled | boolean | ||
states | array of WorkflowStateResponse | ||
transitions | array of WorkflowTransitionResponse | ||
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/schema/workflows/{slug}
Summary: Delete Workflow
Delete a workflow.
POST /api/v1/cms/schema/workflows/create-default
Summary: Create Default Workflow
Create the default publishing workflow for the organization.
This creates a standard workflow with states: Draft → Review → Published → Archived and appropriate transitions between them.
GET /api/v1/cms/content/{type_slug}
Summary: List Entries
List content entries for a content type.
Response Schema (ContentListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
items | array of ContentEntryResponse | * | |
total | integer | * | |
limit | integer | * | |
offset | integer | * | |
page | integer | ||
pages | integer |
POST /api/v1/cms/content/{type_slug}
Summary: Create Entry
Create a new content entry.
Request Schema (ContentEntryCreate):
| Property | Type | Required | Description |
|---|---|---|---|
data | object | * | Field values as JSON object |
localized_data | object | Per-locale field overrides: {locale: {field: value}} |
Response Schema (ContentEntryResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
content_type_id | string | * | |
content_type_slug | any | ||
org_id | string | * | |
data | object | ||
localized_data | object | ||
status | string | ||
workflow_state | any | ||
version | integer | ||
slug | any | ||
created_by | string | * | |
updated_by | any | ||
published_at | any | ||
created_at | string | * | |
updated_at | string | * |
GET /api/v1/cms/content/{type_slug}/{entry_id}
Summary: Get Entry
Get a content entry by ID.
Response Schema (ContentEntryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
content_type_id | string | * | |
content_type_slug | any | ||
org_id | string | * | |
data | object | ||
localized_data | object | ||
status | string | ||
workflow_state | any | ||
version | integer | ||
slug | any | ||
created_by | string | * | |
updated_by | any | ||
published_at | any | ||
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/cms/content/{type_slug}/{entry_id}
Summary: Update Entry
Update a content entry.
Request Schema (ContentEntryUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
data | object | * | Field values to update |
localized_data | any | ||
change_summary | any | Description of changes |
Response Schema (ContentEntryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
content_type_id | string | * | |
content_type_slug | any | ||
org_id | string | * | |
data | object | ||
localized_data | object | ||
status | string | ||
workflow_state | any | ||
version | integer | ||
slug | any | ||
created_by | string | * | |
updated_by | any | ||
published_at | any | ||
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/content/{type_slug}/{entry_id}
Summary: Delete Entry
Delete a content entry.
POST /api/v1/cms/content/{type_slug}/{entry_id}/transition
Summary: Transition Entry
Transition entry to a new workflow state.
Request Schema (TransitionRequest):
| Property | Type | Required | Description |
|---|---|---|---|
to_state | string | * | Target state slug |
comment | any | Transition comment/reason |
Response Schema (ContentEntryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
content_type_id | string | * | |
content_type_slug | any | ||
org_id | string | * | |
data | object | ||
localized_data | object | ||
status | string | ||
workflow_state | any | ||
version | integer | ||
slug | any | ||
created_by | string | * | |
updated_by | any | ||
published_at | any | ||
created_at | string | * | |
updated_at | string | * |
GET /api/v1/cms/content/{type_slug}/{entry_id}/available-transitions
Summary: Get Available Transitions
Get available workflow transitions for an entry.
GET /api/v1/cms/content/{type_slug}/{entry_id}/versions
Summary: Get Versions
Get version history for an entry.
POST /api/v1/cms/content/{type_slug}/{entry_id}/versions/{version}/restore
Summary: Restore Version
Restore an entry to a previous version.
Response Schema (ContentEntryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
content_type_id | string | * | |
content_type_slug | any | ||
org_id | string | * | |
data | object | ||
localized_data | object | ||
status | string | ||
workflow_state | any | ||
version | integer | ||
slug | any | ||
created_by | string | * | |
updated_by | any | ||
published_at | any | ||
created_at | string | * | |
updated_at | string | * |
POST /api/v1/cms/content/{type_slug}/bulk-delete
Summary: Bulk Delete
Bulk delete multiple entries.
POST /api/v1/cms/content/{type_slug}/bulk-transition
Summary: Bulk Transition
Bulk transition multiple entries to a new state.
GET /api/v1/cms/delivery/{type_slug}
Summary: List Published
List published content entries.
Only returns entries in a published workflow state. Supports pagination and sorting.
GET /api/v1/cms/delivery/{type_slug}/by-slug/{slug}
Summary: Get By Slug
Get a published entry by its slug.
Returns 404 if entry doesn't exist or isn't published.
GET /api/v1/cms/delivery/{type_slug}/_schema
Summary: Get Type Schema
Get the schema for a content type.
Useful for client SDKs to understand the structure.
GET /api/v1/cms/delivery/{type_slug}/singleton
Summary: Get Singleton
Get singleton content (for types with is_singleton=true).
Returns the single published entry for singleton types like settings pages.
GET /api/v1/cms/delivery/_cache/stats
Summary: Get Cache Stats
Get CMS delivery API cache statistics.
Returns hit rate, miss count, and other cache metrics. Useful for monitoring cache effectiveness.
POST /api/v1/cms/delivery/_cache/clear
Summary: Clear Cache
Clear all CMS delivery API caches for the organization.
Use with caution - this will cause a temporary increase in database load until caches are repopulated.
GET /api/v1/cms/delivery/{type_slug}/{entry_id}
Summary: Get By Id
Get a published entry by its ID.
Returns 404 if entry doesn't exist or isn't published.
GET /api/v1/cms/media/folders
Summary: List Folders
List media folders.
POST /api/v1/cms/media/folders
Summary: Create Folder
Create a new media folder.
Request Schema (MediaFolderCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
parent_id | any |
Response Schema (MediaFolderResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
parent_id | any | ||
name | string | * | |
path | string | * | |
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/media/folders/{folder_id}
Summary: Delete Folder
Delete a media folder.
GET /api/v1/cms/media
Summary: List Media
List media files.
Response Schema (MediaListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
items | array of MediaResponse | * | |
total | integer | * | |
limit | integer | * | |
offset | integer | * | |
folders | array of MediaFolderResponse |
GET /api/v1/cms/media/{media_id}
Summary: Get Media
Get a media file by ID.
Response Schema (MediaResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
folder_id | any | ||
filename | string | * | |
original_filename | string | * | |
mime_type | string | * | |
file_size | integer | * | |
storage_provider | string | * | |
storage_key | string | * | |
storage_url | any | ||
url | string | * | |
width | any | ||
height | any | ||
variants | object | ||
alt_text | any | ||
caption | any | ||
title | any | ||
metadata | object | ||
uploaded_by | string | * | |
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/cms/media/{media_id}
Summary: Update Media
Update media metadata.
Request Schema (MediaUpdateRequest):
| Property | Type | Required | Description |
|---|---|---|---|
alt_text | any | ||
caption | any | ||
title | any | ||
folder_id | any |
Response Schema (MediaResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
folder_id | any | ||
filename | string | * | |
original_filename | string | * | |
mime_type | string | * | |
file_size | integer | * | |
storage_provider | string | * | |
storage_key | string | * | |
storage_url | any | ||
url | string | * | |
width | any | ||
height | any | ||
variants | object | ||
alt_text | any | ||
caption | any | ||
title | any | ||
metadata | object | ||
uploaded_by | string | * | |
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/media/{media_id}
Summary: Delete Media
Delete a media file.
POST /api/v1/cms/media/upload
Summary: Upload Media
Upload a new media file.
Response Schema (MediaResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
folder_id | any | ||
filename | string | * | |
original_filename | string | * | |
mime_type | string | * | |
file_size | integer | * | |
storage_provider | string | * | |
storage_key | string | * | |
storage_url | any | ||
url | string | * | |
width | any | ||
height | any | ||
variants | object | ||
alt_text | any | ||
caption | any | ||
title | any | ||
metadata | object | ||
uploaded_by | string | * | |
created_at | string | * | |
updated_at | string | * |
POST /api/v1/cms/media/{media_id}/move
Summary: Move Media
Move media to a different folder.
Response Schema (MediaResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
folder_id | any | ||
filename | string | * | |
original_filename | string | * | |
mime_type | string | * | |
file_size | integer | * | |
storage_provider | string | * | |
storage_key | string | * | |
storage_url | any | ||
url | string | * | |
width | any | ||
height | any | ||
variants | object | ||
alt_text | any | ||
caption | any | ||
title | any | ||
metadata | object | ||
uploaded_by | string | * | |
created_at | string | * | |
updated_at | string | * |
POST /api/v1/cms/media/{media_id}/generate-variants
Summary: Generate Variants
Generate image variants (thumbnails, responsive sizes).
Response Schema (MediaResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
folder_id | any | ||
filename | string | * | |
original_filename | string | * | |
mime_type | string | * | |
file_size | integer | * | |
storage_provider | string | * | |
storage_key | string | * | |
storage_url | any | ||
url | string | * | |
width | any | ||
height | any | ||
variants | object | ||
alt_text | any | ||
caption | any | ||
title | any | ||
metadata | object | ||
uploaded_by | string | * | |
created_at | string | * | |
updated_at | string | * |
POST /api/v1/cms/media/bulk-delete
Summary: Bulk Delete
Bulk delete multiple media files.
POST /api/v1/cms/media/bulk-move
Summary: Bulk Move
Bulk move multiple media files to a folder.
GET /api/v1/cms/webhooks
Summary: List Webhooks
List all webhooks for the organization.
POST /api/v1/cms/webhooks
Summary: Create Webhook
Create a new webhook.
Request Schema (WebhookCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | |
description | any | ||
url | string | * | Target URL for webhook delivery |
secret | any | Secret for HMAC signature | |
events | array of string | * | Event types to trigger on |
content_types | array of string | Content type slugs to filter | |
is_enabled | boolean | ||
retry_count | integer | ||
timeout_seconds | integer | ||
headers | object |
Response Schema (WebhookResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
name | string | * | |
description | any | ||
url | string | * | |
events | array of string | ||
content_types | array of string | ||
is_enabled | boolean | ||
retry_count | integer | ||
timeout_seconds | integer | ||
headers | object | ||
created_at | string | * | |
updated_at | string | * |
GET /api/v1/cms/webhooks/{webhook_id}
Summary: Get Webhook
Get a webhook by ID.
Response Schema (WebhookResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
name | string | * | |
description | any | ||
url | string | * | |
events | array of string | ||
content_types | array of string | ||
is_enabled | boolean | ||
retry_count | integer | ||
timeout_seconds | integer | ||
headers | object | ||
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/cms/webhooks/{webhook_id}
Summary: Update Webhook
Update a webhook.
Request Schema (WebhookUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | ||
description | any | ||
url | any | ||
secret | any | ||
events | any | ||
content_types | any | ||
is_enabled | any | ||
retry_count | any | ||
timeout_seconds | any | ||
headers | any |
Response Schema (WebhookResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
org_id | string | * | |
name | string | * | |
description | any | ||
url | string | * | |
events | array of string | ||
content_types | array of string | ||
is_enabled | boolean | ||
retry_count | integer | ||
timeout_seconds | integer | ||
headers | object | ||
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/cms/webhooks/{webhook_id}
Summary: Delete Webhook
Delete a webhook.
POST /api/v1/cms/webhooks/{webhook_id}/test
Summary: Test Webhook
Send a test event to a webhook.
Response Schema (WebhookTestResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
success | boolean | * | |
status_code | any | ||
response_time_ms | any | ||
error_message | any | ||
delivery_id | string | * |
GET /api/v1/cms/webhooks/{webhook_id}/deliveries
Summary: Get Deliveries
Get delivery history for a webhook.
GET /api/v1/cms/webhooks/{webhook_id}/deliveries/{delivery_id}
Summary: Get Delivery
Get a specific delivery record.
Response Schema (WebhookDeliveryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
webhook_id | string | * | |
event_type | string | * | |
payload | object | * | |
status_code | any | ||
response_body | any | ||
response_time_ms | any | ||
success | any | ||
error_message | any | ||
attempt_count | integer | ||
created_at | string | * |
POST /api/v1/cms/webhooks/{webhook_id}/deliveries/{delivery_id}/retry
Summary: Retry Delivery
Manually retry a failed delivery.
Response Schema (WebhookDeliveryResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
webhook_id | string | * | |
event_type | string | * | |
payload | object | * | |
status_code | any | ||
response_body | any | ||
response_time_ms | any | ||
success | any | ||
error_message | any | ||
attempt_count | integer | ||
created_at | string | * |
GET /api/v1/cms/webhooks/events/supported
Summary: Get Supported Events
Get list of supported webhook events.
GET /
Summary: Root
Root endpoint with API information.
Additional current operations
The following operations are also present in the current application schema.
They are listed here because they are easy to miss when browsing the grouped
reference pages; /openapi.json remains authoritative for their schemas.
DELETE /api/v1/phone-numbers/{phone_number_id}
Delete a configured phone number.
GET /api/v1/cms/content/{type_slug}/export
Export CMS content for a content type.
GET /api/v1/projects/{project_id}/phone-numbers
List phone numbers assigned to a project.
GET /api/v1/telephony/numbers/search
Search available telephony numbers.
POST /api/v1/billing/webhooks/flutterwave
Receive a Flutterwave billing webhook in SaaS mode.
POST /api/v1/cms/content/{type_slug}/import
Import CMS content for a content type.
POST /api/v1/cms/content/{type_slug}/publish
Publish CMS content for a content type.
POST /api/v1/credits/flutterwave/checkout
Create a Flutterwave credit checkout session.
POST /api/v1/projects/{project_id}/phone-numbers
Assign or provision a phone number for a project.
POST /api/v1/voice/session
Create a voice session.
POST /api/v1/voice/session/{session_id}/end
End a voice session.
POST /api/v1/voice/tool
Handle a voice tool invocation.
POST /webhooks/email/agentmail
Receive an AgentMail webhook.
POST /webhooks/flutterwave
Receive a root-level Flutterwave webhook.
POST /webhooks/telephony/telnyx
Receive a Telnyx telephony webhook.
POST /webhooks/telephony/vonage/answer
Return a Vonage answer webhook response.
POST /webhooks/telephony/vonage/event
Receive a Vonage telephony event webhook.