AIVAX
AI model inference, document indexing and search.
Helpful links:
- API endpoint: https://inference.aivax.net/
- Reference for agents: https://inference.aivax.net/apidocs/llms.txt
- Documentation/guides: https://docs.aivax.net/
- Terms of service: https://docs.aivax.net/docs/en/legal/terms-of-service
- Privacy Policy: https://docs.aivax.net/docs/en/legal/privacy-policy
Tip for agents: send the header X-Response-Truncating: agent-optimized in your request to get a shortened, optimized response for LLMs reading.
Service version: 1
Inference
Get/v1/modelsModel listing
Model listing
Returns OpenAI-compatible model entries for models and AI Gateways owned by the authenticated account.
GET /v1/modelsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
OpenAI-compatible model list. Gateway entries can be used as the model value in chat completions.
{ "object": "list", "data": [ { "id": "0198683a-2b6d-7066-9598-6ea119c219f2", "object": "model", "created": 1, "owned_by": "example_account" }, { "id": "b2c4f1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "object": "model", "created": 1, "owned_by": "example_account" } ] }
Post/v1/chat/completionsInference (chat completions)
Inference (chat completions)
Creates an OpenAI-compatible chat completion using an integrated model or an AI Gateway. Supports streaming, tool calls, multimodal messages, response schemas and usage metadata. Note: it is recommended to use the long inference endpoint at https://direct.inference.aivax.net/, because this endpoint may take a while to respond on non-streaming responses.
POST /v1/chat/completionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - Sse-Stream-Options
Optional. Use no-ping to disable periodic keep-alive events on streaming responses.
Request parameters:
- $.modelstringRequired
Integrated model name, AI Gateway identifier or AI Gateway slug.
- $.messagesarray
OpenAI-compatible message array. Required unless prompt is supplied.
Examples:
User text content
User message with textual content
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe these inputs briefly." } ] }, { "role": "user", "content": "Alternative, short way to input data" } ] }Assistant message
Assistant message with textual content
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "assistant", "content": "How can I help you today?" } ] }System message
System message with instructions for the assistant
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "system", "content": "Answer concisely and in English." }, { "role": "user", "content": "What is the capital of France?" } ] }Tool call result
Assistant tool call followed by its tool result
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_weather_123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Lisbon\",\"unit\":\"celsius\"}" } } ] }, { "role": "tool", "tool_call_id": "call_weather_123", "content": "{\"temperature\":21,\"unit\":\"celsius\",\"condition\":\"sunny\"}" } ] }User image content
User message with textual and image content
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What's on this image?" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,SGVsbG8sIHdvcmxkIQ==", "detail": "auto" } }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png", "detail": "high" } } ] } ] }User audio content
User message with textual and audio content
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Transcribe the following audio." }, { "type": "input_audio", "input_audio": { "data": "VGhpcyBpcyBhIHRlc3Qu...", "format": "wav" } } ] } ] }User video content
User message with textual and video content
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What happens in the following video?" }, { "type": "video_url", "video_url": { "url": "UHJvZ3JhbWFjYW8gZW0gSmF2YQ==" } }, { "type": "video_url", "video_url": { "url": "https://example.com/video.mp4" } } ] } ] }User file/PDF content
User message with textual and file content
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What's the insights of this report?" }, { "type": "file", "file": { "filename": "document.pdf", "file_data": "data:application/pdf;base64,QmFzZTY0IGVuY29kaW5nIGV4YW1wbGU=" } }, { "type": "file", "file": { "filename": "document.pdf", "file_data": "https://example.com/report.pdf" } } ] } ] } - $.promptstring | array
Alias for $.messages. String or OpenAI-compatible message array accepted as an alternative to messages.
- $.streamboolean
Streams completion events as text/event-stream when true.
- $.metadataobject
Optional string key/value metadata stored with the conversation.
- $.idempotency_keystring
Optional key used to reuse the the observability conversation token. Use one id for the each conversation.
- $.userstring
Optional external user identifier.
- $.temperaturenumber
Optional sampling temperature.
- $.top_pnumber
Optional nucleus sampling value.
- $.top_kinteger
Optional top-k sampling value forwarded to compatible gateways.
- $.seedinteger
Optional sampling seed.
- $.toolsarray
Optional OpenAI-compatible tool definitions.
Examples:
Weather tool
Function tool that retrieves the current weather for a city
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": "What is the current weather in Lisbon?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Gets the current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "City name." }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit" ] } }, "required": [ "city" ], "additionalProperties": false } } } ] } - $.tool_choicestring | object
Optional tool-selection behavior forwarded to compatible gateways.
- $.builtin_toolsobject
Optional AIVAX built-in tool selection and options.
Examples:
Web search and image generation
AIVAX built-in tools for searching the web and generating an image from the findings
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": "Search the web for a recent James Webb Space Telescope discovery, summarize it, and generate an illustration inspired by the findings." } ], "builtin_tools": { "tools": [ "WebSearch", "ImageGeneration" ], "options": { "webSearchMode": "Full", "webSearchMaxResults": 5, "imageGenerationMaxResults": 1, "imageGenerationQuality": "High", "imageGenerationAllowMatureContent": false, "imageGenerationAllowReferenceUsage": true } } } - $.reasoning_effortstring
Optional reasoning effort selector.
- $.verbositystring
Optional response verbosity selector.
- $.max_completion_tokensinteger
Optional maximum completion tokens.
- $.max_tokensinteger
Compatibility alias for max_completion_tokens.
- $.stopstring | array
Optional stop sequence or sequences.
- $.response_formatobject
Optional OpenAI-compatible structured-output format.
- $.response_schemaobject
Optional shorthand JSON schema for structured output.
Examples:
JSON healing after a tool call
Tool result followed by a schema-constrained final response with automatic JSON healing
{ "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": "What is the current weather in Lisbon?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Gets the current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit" ] } }, "required": [ "city" ], "additionalProperties": false } } } ], "response_schema": { "type": "object", "properties": { "city": { "type": "string" }, "temperature": { "type": "number" }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit" ] }, "condition": { "type": "string" } }, "required": [ "city", "temperature", "unit", "condition" ], "additionalProperties": false } } - $.extra_bodyobject
Optional provider-specific request fields; supported only with AI Gateways with BYOK.
- $.service_tierstring
Optional provider service tier; supported only with AI Gateways with BYOK.
Request examples:
OpenAI-compatible chat completion payload. Use model for an integrated model name, gateway id or gateway slug; messages or prompt for input; stream for SSE output; metadata for string key/value request metadata stored with the conversation; idempotency_key to reuse the stored conversation token; and tools, builtin_tools or response_format when tool calling or structured output is required.
{ "model": "0198683a-2b6d-7066-9598-6ea119c219f2", "messages": [ { "role": "user", "content": "Qual a capital da França?" } ], "stream": false, "idempotency_key": "order-123-summary", "metadata": { "foo": "bar" } }
Responses:
- 200
OpenAI-compatible chat completion response. Non-streaming responses include usage and AIVAX generation_context metadata.
{ "id": "0198d24c-c9ce-70fe-9cf3-00644ef5f2e2", "object": "chat.completion", "created": 1755874904, "model": "@openai/gpt-5-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "A capital da França é Paris.", "refusal": null, "annotations": [], "tool_calls": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 84, "completion_tokens": 16, "total_tokens": 1892, "prompt_tokens_details": { "cached_tokens": 1792 } }, "service_tier": "default", "generation_context": { "generated_usage": [ { "sku": "inference.resolving.routing_complexity.in", "amount": 0.0000207, "unit_price": 7.5e-8, "quantity": 276, "description": "Inference for model routing" }, { "sku": "inference.resolving.routing_complexity.out", "amount": 3e-7, "unit_price": 3e-7, "quantity": 1, "description": "Inference for model routing" }, { "sku": "inference.chat_completions.in", "amount": 0.000021, "unit_price": 2.5e-7, "quantity": 84, "description": "Inference for AI model '@openai/gpt-5-mini'" }, { "sku": "inference.chat_completions.out", "amount": 0.000032, "unit_price": 0.000002, "quantity": 16, "description": "Inference for AI model '@openai/gpt-5-mini'" }, { "sku": "inference.chat_completions.in.cached", "amount": 0.0000448, "unit_price": 2.5e-8, "quantity": 1792, "description": "Inference for AI model '@openai/gpt-5-mini'" } ], "runned_functions": [] } }
Web
Post/api/v1/web/fetchFetch web contents
Fetch web contents
Extracts readable text from URLs or base64 data URIs. Each item is limited to 10 MB.
POST /api/v1/web/fetchHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.contentsarrayRequired
Non-empty URL or base64 data URI values to extract.
Examples:
Web pages
Extracts readable content from public web pages.
{ "contents": [ "https://example.com/article", "https://example.org/documentation" ], "returnErrors": true }Inline files (data url)
Extracts an inline file supplied as a base64 data URI with its MIME type. This example encodes a plain-text file containing Hello world.
{ "contents": [ "data:text/plain;base64,SGVsbG8gd29ybGQ=" ], "returnErrors": true }External files
Extracts content from direct public file URLs. Replace the example URLs with accessible files in supported formats.
{ "contents": [ "https://example.com/files/manual.pdf", "https://example.com/files/receipt.png", "https://example.com/files/report.docx" ], "returnErrors": true } - $.returnErrorsboolean
Returns an error item for an individual failed content value when true.
Request examples:
Contents to fetch and extract.
{ "contents": [ "https://example.com/article", "data:text/plain;base64,SGVsbG8gd29ybGQ=" ], "returnErrors": true }
Responses:
- 200
{ "message": null, "data": { "results": [ { "index": number, "extractedText": string?, "processingUnits": number, "error": string? }, ... ] } }{ "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "extractedText": { "type": [ "string", "null" ] }, "processingUnits": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "error": { "type": [ "string", "null" ] } } } } } } - 400
The contents array is missing, empty or contains invalid data URIs.
- 402
The account does not have a positive balance.
- 429
The request rate was exceeded.
Post/api/v1/web/searchSearch the web
Search the web
Searches the web with optional country, language and domain filters.
POST /api/v1/web/searchHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.querystringRequired
Search query.
- $.topninteger
Optional result count from 1 to 25.
- $.countrystring
Optional two-letter ISO 3166-1 country code.
- $.languagestring
Optional language code.
- $.includeDomainsarray
Optional domain allowlist.
Examples:
Domain allowlist
Restricts results to the supplied domains.
{ "query": "latest artificial intelligence research", "topn": 5, "country": "US", "language": "en", "includeDomains": [ "arxiv.org", "nature.com" ] }
Request examples:
Web search parameters.
{ "query": "latest artificial intelligence research", "topn": 5, "country": "US", "language": "en", "includeDomains": [ "arxiv.org", "nature.com" ] }
Responses:
- 200
{ "message": null, "data": { "results": [ { "url": string, "title": string, "text": string }, ... ] } }{ "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" } } } } } } - 400
The query or optional search filters are invalid.
- 402
The account does not have a positive balance.
- 429
The request rate was exceeded.
Hook Schedules
Get/api/v1/web-chat-clients/<web-chat-id>/hook-schedulesList Hook Schedules
List Hook Schedules
Lists one-time hook schedules, recurring hook tasks and recently inactive users for a web chat client.
GET /api/v1/web-chat-clients/<web-chat-id>/hook-schedulesHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- web-chat-iduuid
Identifier of the web chat client.
Query parameters:
- external-user-idstring
Optional external user id used to restrict schedules and recurring tasks.
Responses:
- 200
Schedules, recurring tasks and inactive-user candidates for the web chat client.
{ "message": null, "data": { "webChat": { "id": "...", "name": "My Web Chat" }, "inactiveUsers": [ { "externalUserId": "user-456", "lastScheduledMessageAt": "2026-03-20T15:00:00Z", "lastUserMessageAt": "2026-03-18T09:30:00Z" } ], "schedules": [ { "id": "...", "externalUserId": "user-123", "target": "Telegram", "targetIdentifier": "\u002B5511999999999", "scheduledTime": "2026-03-21T15:00:00Z", "activatedAt": null, "createdAt": "2026-03-20T10:00:00Z" } ], "recurringTasks": [ { "id": "...", "externalUserId": "user-123", "target": "WhatsApp_ZApi", "targetIdentifier": "\u002B5511988888888", "cronExpression": "0 9 * * 1", "nextActivation": "2026-03-23T09:00:00Z", "lastActivation": null, "executionCount": 0, "createdAt": "2026-03-20T10:00:00Z" } ] } }
Get/api/v1/web-chat-clients/<web-chat-id>/hook-schedules/schedules/<id>Get Schedule
Get Schedule
Returns one pending, activated or failed one-time hook activation schedule for a web chat client.
GET /api/v1/web-chat-clients/<web-chat-id>/hook-schedules/schedules/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- web-chat-iduuid
Identifier of the web chat client.
- iduuid
Identifier of the one-time schedule.
Responses:
- 200
One-time schedule details.
{ "message": null, "data": { "id": "...", "externalUserId": "user-123", "target": "Telegram", "targetIdentifier": "\u002B5511999999999", "scheduledTime": "2026-03-21T15:00:00Z", "reason": "Follow-up reminder", "context": "{ \u0022orderId\u0022: 42 }", "createdAt": "2026-03-20T10:00:00Z", "activatedAt": null, "activatedSessionId": null, "activationResult": null } } - 404
Schedule not found.
Delete/api/v1/web-chat-clients/<web-chat-id>/hook-schedules/schedules/<id>Cancel Schedule
Cancel Schedule
Deletes one hook activation schedule from a web chat client.
DELETE /api/v1/web-chat-clients/<web-chat-id>/hook-schedules/schedules/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- web-chat-iduuid
Identifier of the web chat client.
- iduuid
Identifier of the schedule to delete.
Responses:
- 200
The schedule was deleted.
- 404
Schedule not found.
Get/api/v1/web-chat-clients/<web-chat-id>/hook-schedules/recurring/<id>Get Recurring Task
Get Recurring Task
Returns one recurring hook activation task, including cron expression, activation counts and next activation time.
GET /api/v1/web-chat-clients/<web-chat-id>/hook-schedules/recurring/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- web-chat-iduuid
Identifier of the web chat client.
- iduuid
Identifier of the recurring task.
Responses:
- 200
Recurring task details.
{ "message": null, "data": { "id": "...", "externalUserId": "user-123", "target": "WhatsApp_ZApi", "targetIdentifier": "\u002B5511988888888", "jobDescription": "Weekly check-in message", "cronExpression": "0 9 * * 1", "lastActivation": null, "nextActivation": "2026-03-23T09:00:00Z", "maxExecutions": 10, "executionCount": 2, "createdAt": "2026-03-20T10:00:00Z" } } - 404
Recurring task not found.
Delete/api/v1/web-chat-clients/<web-chat-id>/hook-schedules/recurring/<id>Cancel Recurring Task
Cancel Recurring Task
Deletes one recurring hook activation task from a web chat client.
DELETE /api/v1/web-chat-clients/<web-chat-id>/hook-schedules/recurring/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- web-chat-iduuid
Identifier of the web chat client.
- iduuid
Identifier of the recurring task to delete.
Responses:
- 200
The recurring task was deleted.
- 404
Recurring task not found.
Web Chat
Get/api/v1/web-chat-clientList Web Chat Clients
List Web Chat Clients
Lists web chat clients owned by the authenticated account with active session counts and linked gateway summaries.
GET /api/v1/web-chat-clientHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", "name": string, "color": string?, "activeSessions": number, "associatedGateway": { // UUID/GUID string "id": "uuid", "name": string, "modelName": string }? }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "activeSessions": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "associatedGateway": { "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "modelName": { "type": "string" } }, "type": [ "object", "null" ] } } } }
Post/api/v1/web-chat-clientCreate Web Chat Client
Create Web Chat Client
Creates a web chat client linked to an AI Gateway for browser chat sessions and optional messaging integrations.
POST /api/v1/web-chat-clientHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
Web chat client creation payload.
{ "name": string, // Nullable. UUID/GUID string "aiGatewayId": "uuid"?, "limitingParameters": { "messagesPerHour": number, "maxMessages": number }, "clientParameters": { "languageCode": string?, "suggestionButtons": [ { "label": string, "prompt": string }, ... ], "customScripts": string?, "customStyles": string?, "inputModes": [ "Image", ... ], "primaryColor": string, "pageTitle": string, "helloLabel": string?, "helloSubLabel": string?, "textAreaPlaceholder": string?, "logoImageUrl": string?, "debug": boolean, "showToolCalls": boolean, "allowedFrameOrigins": [ string, ... ], "audioSynthesisSource": "None", "audioSynthesisVoice": string?, "audioSynthesisInstruction": string?, "summarizeTextBeforeAudioSynthesis": boolean, "uploadUnsupportedFiles": boolean, "allowScheduledContinuations": boolean, "splitAnswerIntoMessageChunks": boolean, "maxScheduledIgnoredZone": any, "messageDebounceInterval": any } }{ "type": "object", "properties": { "name": { "type": "string" }, "aiGatewayId": { "format": "uuid", "description": "UUID/GUID string", "type": [ "string", "null" ] }, "limitingParameters": { "type": "object", "properties": { "messagesPerHour": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "maxMessages": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "clientParameters": { "type": "object", "properties": { "languageCode": { "type": [ "string", "null" ] }, "suggestionButtons": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "prompt": { "type": "string" } } } }, "customScripts": { "type": [ "string", "null" ] }, "customStyles": { "type": [ "string", "null" ] }, "inputModes": { "type": "array", "items": { "type": "string", "enum": [ "Image", "Document", "Audio" ] } }, "primaryColor": { "type": "string" }, "pageTitle": { "type": "string" }, "helloLabel": { "type": [ "string", "null" ] }, "helloSubLabel": { "type": [ "string", "null" ] }, "textAreaPlaceholder": { "type": [ "string", "null" ] }, "logoImageUrl": { "type": [ "string", "null" ] }, "debug": { "type": "boolean" }, "showToolCalls": { "type": "boolean" }, "allowedFrameOrigins": { "type": "array", "items": { "type": "string" } }, "audioSynthesisSource": { "type": "string", "enum": [ "None", "Gpt4oTts", "ElevenMultilingualV2", "ElevenV3", "GrokVoice", "GrokVoice_Alt", "ElevenFlash" ] }, "audioSynthesisVoice": { "type": [ "string", "null" ] }, "audioSynthesisInstruction": { "type": [ "string", "null" ] }, "summarizeTextBeforeAudioSynthesis": { "type": "boolean" }, "uploadUnsupportedFiles": { "type": "boolean" }, "allowScheduledContinuations": { "type": "boolean" }, "splitAnswerIntoMessageChunks": { "type": "boolean" }, "maxScheduledIgnoredZone": {}, "messageDebounceInterval": {} } } } }
Responses:
- 200
{ "message": null, "data": { "id": "uuid" } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } } }
Get/api/v1/web-chat-client/<id>View Web Chat Client
View Web Chat Client
Returns the web chat client's gateway link, rate limits, UI/client parameters and messaging integration settings.
GET /api/v1/web-chat-client/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the web chat client to retrieve.
Responses:
- 200
{ "message": null, "data": { "name": string, "aiGateway": { // UUID/GUID string "id": "uuid", "name": string }?, "limitingParameters": { "messagesPerHour": number, "maxMessages": number }, "clientParameters": { "languageCode": string?, "suggestionButtons": [ { "label": string, "prompt": string }, ... ], "customScripts": string?, "customStyles": string?, "inputModes": [ "Image", ... ], "primaryColor": string, "pageTitle": string, "helloLabel": string?, "helloSubLabel": string?, "textAreaPlaceholder": string?, "logoImageUrl": string?, "debug": boolean, "showToolCalls": boolean, "allowedFrameOrigins": [ string, ... ], "audioSynthesisSource": "None", "audioSynthesisVoice": string?, "audioSynthesisInstruction": string?, "summarizeTextBeforeAudioSynthesis": boolean, "uploadUnsupportedFiles": boolean, "allowScheduledContinuations": boolean, "splitAnswerIntoMessageChunks": boolean, "maxScheduledIgnoredZone": any, "messageDebounceInterval": any }, "integrations": { "zapiIntegration": { "instanceId": string, "instanceToken": string, "clientToken": string?, "sessionDuration": any }?, "telegramIntegration": { "botToken": string, "sessionDuration": any }?, "evolutionIntegration": { "endpointUrl": string, "instanceName": string, "apiKey": string, "sessionDuration": any }?, "kapsoIntegration": { "apiKey": string, "phoneNumberId": string, "webhookSecretKey": string?, "continuedMessagesTemplateId": string?, "sessionDuration": any }? } } }{ "type": "object", "properties": { "name": { "type": "string" }, "aiGateway": { "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "limitingParameters": { "type": "object", "properties": { "messagesPerHour": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "maxMessages": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "clientParameters": { "type": "object", "properties": { "languageCode": { "type": [ "string", "null" ] }, "suggestionButtons": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "prompt": { "type": "string" } } } }, "customScripts": { "type": [ "string", "null" ] }, "customStyles": { "type": [ "string", "null" ] }, "inputModes": { "type": "array", "items": { "type": "string", "enum": [ "Image", "Document", "Audio" ] } }, "primaryColor": { "type": "string" }, "pageTitle": { "type": "string" }, "helloLabel": { "type": [ "string", "null" ] }, "helloSubLabel": { "type": [ "string", "null" ] }, "textAreaPlaceholder": { "type": [ "string", "null" ] }, "logoImageUrl": { "type": [ "string", "null" ] }, "debug": { "type": "boolean" }, "showToolCalls": { "type": "boolean" }, "allowedFrameOrigins": { "type": "array", "items": { "type": "string" } }, "audioSynthesisSource": { "type": "string", "enum": [ "None", "Gpt4oTts", "ElevenMultilingualV2", "ElevenV3", "GrokVoice", "GrokVoice_Alt", "ElevenFlash" ] }, "audioSynthesisVoice": { "type": [ "string", "null" ] }, "audioSynthesisInstruction": { "type": [ "string", "null" ] }, "summarizeTextBeforeAudioSynthesis": { "type": "boolean" }, "uploadUnsupportedFiles": { "type": "boolean" }, "allowScheduledContinuations": { "type": "boolean" }, "splitAnswerIntoMessageChunks": { "type": "boolean" }, "maxScheduledIgnoredZone": {}, "messageDebounceInterval": {} } }, "integrations": { "type": "object", "properties": { "zapiIntegration": { "properties": { "instanceId": { "type": "string" }, "instanceToken": { "type": "string" }, "clientToken": { "type": [ "string", "null" ] }, "sessionDuration": {} }, "required": [ "instanceId", "instanceToken" ], "type": [ "object", "null" ] }, "telegramIntegration": { "properties": { "botToken": { "type": "string" }, "sessionDuration": {} }, "required": [ "botToken" ], "type": [ "object", "null" ] }, "evolutionIntegration": { "properties": { "endpointUrl": { "type": "string" }, "instanceName": { "type": "string" }, "apiKey": { "type": "string" }, "sessionDuration": {} }, "required": [ "endpointUrl", "instanceName", "apiKey" ], "type": [ "object", "null" ] }, "kapsoIntegration": { "properties": { "apiKey": { "type": "string" }, "phoneNumberId": { "type": "string" }, "webhookSecretKey": { "type": [ "string", "null" ] }, "continuedMessagesTemplateId": { "type": [ "string", "null" ] }, "sessionDuration": {} }, "required": [ "apiKey", "phoneNumberId" ], "type": [ "object", "null" ] } } } } }
Put/api/v1/web-chat-client/<id>Edit Web Chat Client
Edit Web Chat Client
Updates an existing web chat client. The request may contain only the fields to change; omitted fields keep their current values. clientParameters and limitingParameters are shallow-merged with the existing objects, replacing only supplied top-level keys.
PUT /api/v1/web-chat-client/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the web chat client to update.
Request examples:
Partial web chat client update data. The schema type documents the available fields, but update payloads may send only name, aiGatewayId, limitingParameters and/or clientParameters.
{ "name": string, // Nullable. UUID/GUID string "aiGatewayId": "uuid"?, "limitingParameters": { "messagesPerHour": number, "maxMessages": number }, "clientParameters": { "languageCode": string?, "suggestionButtons": [ { "label": string, "prompt": string }, ... ], "customScripts": string?, "customStyles": string?, "inputModes": [ "Image", ... ], "primaryColor": string, "pageTitle": string, "helloLabel": string?, "helloSubLabel": string?, "textAreaPlaceholder": string?, "logoImageUrl": string?, "debug": boolean, "showToolCalls": boolean, "allowedFrameOrigins": [ string, ... ], "audioSynthesisSource": "None", "audioSynthesisVoice": string?, "audioSynthesisInstruction": string?, "summarizeTextBeforeAudioSynthesis": boolean, "uploadUnsupportedFiles": boolean, "allowScheduledContinuations": boolean, "splitAnswerIntoMessageChunks": boolean, "maxScheduledIgnoredZone": any, "messageDebounceInterval": any } }{ "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "aiGatewayId": { "type": [ "string", "null" ], "format": "uuid" }, "limitingParameters": { "type": "object", "description": "Partial limiting parameters object. This is shallow-merged with current limiting parameters." }, "clientParameters": { "type": "object", "description": "Partial client parameters object. This is shallow-merged with current client parameters." } } }
Responses:
- 200
The web chat client was updated.
Delete/api/v1/web-chat-client/<id>Delete Web Chat Client
Delete Web Chat Client
Deletes a web chat client owned by the authenticated account.
DELETE /api/v1/web-chat-client/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the web chat client to delete.
Responses:
- 200
The web chat client was deleted.
Put/api/v1/web-chat-client/<id>/integrationsEdit Web Chat Client Integrations
Edit Web Chat Client Integrations
Updates integrations for a web chat client. integrationType is required. The selected integration payload may be partial; it is shallow-merged with the existing integration parameters and only supplied top-level keys are replaced.
PUT /api/v1/web-chat-client/<id>/integrationsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the web chat client whose integration will be updated.
Request examples:
Integration update data. The schema type documents the available fields. Include integrationType and the selected integration object inside integrations; that integration object may be partial.
{ "integrationType": "Zapi", "integrations": { "zapiIntegration": { "instanceId": string, "instanceToken": string, "clientToken": string?, "sessionDuration": any }?, "telegramIntegration": { "botToken": string, "sessionDuration": any }?, "evolutionIntegration": { "endpointUrl": string, "instanceName": string, "apiKey": string, "sessionDuration": any }?, "kapsoIntegration": { "apiKey": string, "phoneNumberId": string, "webhookSecretKey": string?, "continuedMessagesTemplateId": string?, "sessionDuration": any }? } }{ "type": "object", "additionalProperties": false, "required": [ "integrationType", "integrations" ], "properties": { "integrationType": { "type": "string", "enum": [ "Zapi", "Telegram", "EvolutionApi", "Kapso" ] }, "integrations": { "type": "object", "description": "Container for the selected integration payload. The selected integration object is shallow-merged with current integration parameters.", "properties": { "zapiIntegration": { "type": "object" }, "telegramIntegration": { "type": "object" }, "evolutionIntegration": { "type": "object" }, "kapsoIntegration": { "type": "object" } } } } }
Responses:
- 200
The selected integration configuration was updated.
Delete/api/v1/web-chat-client/<id>/integrations/<name>Delete Web Chat Client Integration
Delete Web Chat Client Integration
Removes one messaging integration configuration from a web chat client.
DELETE /api/v1/web-chat-client/<id>/integrations/<name>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the web chat client.
- namestring
Integration name to remove: Zapi, Telegram, EvolutionApi or Kapso.
Responses:
- 200
The selected integration configuration was removed.
Web Chat Sessions
Post/api/v1/web-chat-client/<chat-client-id>/sessionsCreate Web Chat Session
Create Web Chat Session
Creates a web chat session for a client, or refreshes the existing session when the same tag already exists.
POST /api/v1/web-chat-client/<chat-client-id>/sessionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- chat-client-iduuid
Identifier of the web chat client that owns the session.
Request examples:
Session creation payload.
{ "extraContext": string?, "tag": string?, "expires": number, "contextLocation": string?, "metadata": {}? }{ "type": "object", "properties": { "extraContext": { "type": [ "string", "null" ] }, "tag": { "type": [ "string", "null" ] }, "expires": { "type": "number" }, "contextLocation": { "type": [ "string", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "type": [ "object", "null" ] } } }
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "sessionId": "uuid", "accessKey": string, "talkUrl": string } }{ "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "accessKey": { "type": "string" }, "talkUrl": { "type": "string" } } }
Get/api/v1/web-chat-client/<chat-client-id>/sessionsList Web Chat Sessions
List Web Chat Sessions
Lists up to 300 sessions for a web chat client, including context preview, tag, timestamps, message count and token count.
GET /api/v1/web-chat-client/<chat-client-id>/sessionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- chat-client-iduuid
Identifier of the web chat client whose sessions will be listed.
Query parameters:
- filterstring
Optional search over access key, extra context, external user id or exact session id.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", "tagName": string?, "contextPreview": string?, "sessionKey": string, // ISO 8601 date-time string "createdAt": "date-time", // Nullable. ISO 8601 date-time string "lastMessage": "date-time"?, "messageCount": number, "tokenCount": number }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "tagName": { "type": [ "string", "null" ] }, "contextPreview": { "type": [ "string", "null" ] }, "sessionKey": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "lastMessage": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "messageCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "tokenCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } } }
Delete/api/v1/web-chat-client/<chat-client-id>/sessions/<session-id>Delete Web Chat Session
Delete Web Chat Session
Deletes a web chat session from a client, ending access through its session key.
DELETE /api/v1/web-chat-client/<chat-client-id>/sessions/<session-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- chat-client-iduuid
Identifier of the web chat client that owns the session.
- session-iduuid
Identifier of the session to delete.
Responses:
- 200
The session was ended and deleted.
Voice Sessions
Get/api/v1/voice-sessionOpen realtime voice session
Open realtime voice session
Opens an authenticated WebSocket connection using the OpenAI-compatible Realtime event protocol. The first client message must be a session.update event. The event can include gateway and model selectors at the event level or inside session. Standard realtime session fields such as audio.output.voice, reasoning.effort, instructions and tools are supported.
GET /api/v1/voice-sessionHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 101
The WebSocket connection was accepted.
- 400
The request is not a valid WebSocket upgrade or the initial event is invalid.
- 401
The API key is missing, invalid or public.
Skills
Get/api/v1/skillsList Skills
List Skills
Lists skills owned by the authenticated account with slug, description and allowed-tool count.
GET /api/v1/skillsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- filterstring
Optional search over skill id, slug or description.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "slug": string, "description": string?, "allowedToolsCount": number }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "allowedToolsCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } } }
Post/api/v1/skillsCreate Skill
Create Skill
Creates a reusable instruction package that can be enabled on AI Gateways and can limit which tools are visible.
POST /api/v1/skillsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
Skill creation payload.
{ "slug": string, "description": string?, "instructions": string, "options": { "instructionSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "allowedToolsNames": [ string, ... ] } }{ "type": "object", "properties": { "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "instructions": { "type": "string" }, "options": { "type": "object", "properties": { "instructionSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "allowedToolsNames": { "type": "array", "items": { "type": "string" } } } } } }
Responses:
- 200
The skill was created.
Get/api/v1/skills/<skill-id>Get Skill
Get Skill
Returns a skill's slug, instructions, description and tool/instruction-source options.
GET /api/v1/skills/<skill-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- skill-iduuid
Identifier of the skill to retrieve.
Responses:
- 200
Skill configuration details.
Put/api/v1/skills/<skill-id>Update Skill
Update Skill
Updates an existing skill. The request may contain only the fields to change; omitted fields keep their current values. options is shallow-merged with the existing options object, replacing only supplied top-level keys.
PUT /api/v1/skills/<skill-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- skill-iduuid
Identifier of the skill to update.
Request examples:
Partial skill update data. The schema type documents the available fields, but update payloads may send only slug, description, instructions and/or options.
{ "slug": string, "description": string?, "instructions": string, "options": { "instructionSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "allowedToolsNames": [ string, ... ] } }{ "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "instructions": { "type": "string" }, "options": { "type": "object", "description": "Partial skill options object. This is shallow-merged with current options." } } }
Responses:
- 200
The skill was updated.
Delete/api/v1/skills/<skill-id>Delete Skill
Delete Skill
Deletes a skill owned by the authenticated account.
DELETE /api/v1/skills/<skill-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- skill-iduuid
Identifier of the skill to delete.
Responses:
- 200
The skill was deleted.
Delete/api/v1/skills/management/clearClear Skills
Clear Skills
Deletes every skill owned by the authenticated account.
DELETE /api/v1/skills/management/clearHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
All account skills were deleted.
Post/api/v1/skills/management/importImport Skills (JSONL)
Import Skills (JSONL)
Uploads and imports skills from a JSONL file. Each line must be a JSON object with 'slug' and 'instructions' at minimum. See the example for the full schema.
POST /api/v1/skills/management/importHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- skillsfile
JSONL file containing one skill object per line.
Request examples:
Multipart form data with a skills JSONL file. Existing skills are matched by slug and overwritten.
{"slug":"summarizer","description":"Summarizes text","instructions":"You are a summarizer. Summarize the input concisely.","options":{"instructionSources":[],"allowedToolsNames":["web-search"]}} {"slug":"translator","description":"Translates text","instructions":"Translate the input to the target language specified by the user."}
Responses:
- 200
{ "message": null, "data": { "enqueued": number, "skipped": number } }{ "type": "object", "properties": { "enqueued": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "skipped": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }
Get/api/v1/skills/management/export.jsonlExport Skills (JSONL)
Export Skills (JSONL)
Exports all skills for the authenticated account in JSONL format. Each line is a JSON object with 'slug', 'description', 'instructions', and 'options'.
GET /api/v1/skills/management/export.jsonlHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
JSONL file stream containing one skill object per line.
{ "message": null, "data": { "slug": "summarizer", "description": "Summarizes text", "instructions": "You are a summarizer. Summarize the input concisely.", "options": { "instructionSources": [ ], "allowedToolsNames": [ "web-search" ] } } }
Shell I/O
Get/api/v1/shell/io/fileDownload File
Download File
Downloads one file from the account and X-Shell-User-Id scoped shell sandbox.
GET /api/v1/shell/io/fileHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
File path inside the shell sandbox.
Responses:
- 200
Raw file contents.
- 404
File not found.
Post/api/v1/shell/io/fileUpload File
Upload File
Writes the request body to a file inside the shell sandbox, creating or replacing the file. Maximum request size is 100 MB.
POST /api/v1/shell/io/fileHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
Destination file path inside the shell sandbox.
Responses:
- 200
The file was written.
Delete/api/v1/shell/io/fileDelete File
Delete File
Deletes one file from the shell sandbox.
DELETE /api/v1/shell/io/fileHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
File path inside the shell sandbox.
Responses:
- 200
The file was deleted.
- 404
File not found.
Get/api/v1/shell/io/listingList Directory
List Directory
Lists files and directories inside a shell sandbox scoped by account and X-Shell-User-Id.
GET /api/v1/shell/io/listingHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
Directory path inside the shell sandbox.
Responses:
- 200
Directory entries for the requested sandbox path.
{ "message": null, "data": { "entries": [ { "name": string, "isDirectory": boolean, "size": number?, // ISO 8601 date-time string "lastModifiedUtc": "date-time", // ISO 8601 date-time string "createdAtUtc": "date-time" }, ... ] } }{ "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "isDirectory": { "type": "boolean" }, "size": { "minimum": -9223372036854780000, "maximum": 9223372036854780000, "type": [ "integer", "null" ] }, "lastModifiedUtc": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "createdAtUtc": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" } } } } } } - 404
Directory not found.
Post/api/v1/shell/io/directoryCreate Directory
Create Directory
Creates a directory path inside the shell sandbox.
POST /api/v1/shell/io/directoryHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
Directory path to create inside the shell sandbox.
Responses:
- 200
The directory exists after the request.
Delete/api/v1/shell/io/directoryDelete Directory
Delete Directory
Recursively deletes a non-root directory from the shell sandbox.
DELETE /api/v1/shell/io/directoryHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
Directory path inside the shell sandbox. Root paths are rejected.
Responses:
- 200
The directory and its contents were deleted.
- 400
Attempted to delete the root directory.
- 404
Directory not found.
Get/api/v1/shell/io/file/detailsGet File Details
Get File Details
Returns size, timestamps, MIME type and text-detection metadata for one file in the shell sandbox.
GET /api/v1/shell/io/file/detailsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
File path inside the shell sandbox.
Responses:
- 200
File metadata returned successfully.
{ "message": null, "data": { "data": { "name": "readme.txt", "size": 2048, "createdAtUtc": "2024-01-01T12:00:00Z", "lastModifiedUtc": "2024-01-02T15:30:00Z", "mimeType": "text/plain", "isPlainText": true } } } - 404
File not found.
{ "error": "Error message", "details": { "error_code": "Optional object for error details" } }
Get/api/v1/shell/io/file/public-addressGet File Public Address
Get File Public Address
Creates a temporary public download URL for one file in the shell sandbox.
GET /api/v1/shell/io/file/public-addressHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Shell-User-IdRequired
Application user identifier used to isolate this shell filesystem within the authenticated account.
Query parameters:
- pathstringRequired
File path inside the shell sandbox.
Responses:
- 200
Public file address generated successfully.
{ "message": null, "data": { "data": { "name": "readme.txt", "size": 2048, "publicUrl": "https://example.com/api/v1/public/ext-res/file/abc123" } } } - 404
File not found.
{ "error": "Error message", "details": { "error_code": "Optional object for error details" } }
RAG
Post/api/v1/querySemantic search
Semantic search
Searches one or more RAG collections with semantic similarity and returns matching documents, scores, metadata and optional referenced documents.
POST /api/v1/queryHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.collectionsarrayRequired
Collection UUIDs to search.
- $.termsstring | array
Search string or strings. Required unless term or prompt is supplied.
- $.termstring | array
Compatibility alias for terms.
- $.promptstring | array
Compatibility alias for terms.
- $.topinteger
Optional maximum number of results.
- $.minScorenumber
Optional minimum similarity score.
- $.rerankerstring
Optional reranker identifier.
- $.includeReferencesboolean
Includes referenced document chunks when true.
Request examples:
Semantic search payload. Use terms for one or more search strings, collections for collection identifiers, top for result count, minScore for the similarity cutoff, reranker for result reordering and includeReferences to include referenced documents.
{ "query": [ "What is the capital of France?" ], "collections": [ "0198683a-2b6d-7066-9598-6ea119c219f2", "b2c4f1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d" ], "top": 10, "minScore": 0.7, "includeReferences": true }
Responses:
- 200
Matching documents ordered by score or reranker output.
{ "message": null, "data": [ { "documentId": "019be299-69a7-7668-95d0-3dee083710dc", "documentName": "autogen.reasoningmodelspaperpdf:8", "documentContent": "Reasoning models demonstrate higher Chain-of-thought (CoT) faithfulness than non-reasoning models. The average faithfulness is 3.6 times higher for the Claude series (comparing Claude 3.7 Sonnet to Claude 3.5 Sonnet) and 1.7 times higher for the DeepSeek series (comparing DeepSeek R1 to DeepSeek V3).", "score": 0.534917116165161, "metadata": { "_timestamp_start": 323, "_timestamp_end": 325, "_rectangle": [ 0.23, 0.08, 0.55, 0.92 ] }, "referencedDocuments": [ { "documentId": "019be299-6990-7c9e-9fcd-6c6037b03d16", "documentContent": "Chain-of-thought (CoT) faithfulness is the degree to which a large language model\u0027s (LLM) articulated reasoning accurately reflects the internal process used to reach a conclusion. Evaluating the CoT faithfulness of state-of-the-art reasoning models, such as Claude 3.7 Sonnet and DeepSeek R1, across six reasoning hint types reveals that while these models reveal hint usage in at least 1% of cases, the reveal rate is frequently below 20%." }, { "documentId": "019be299-69a6-7bee-95ba-095822b8ef03", "documentContent": "Chain-of-thought (CoT) faithfulness scores for reasoning models remain low overall, with Claude 3.7 Sonnet averaging 25% and DeepSeek R1 averaging 39%. These scores are particularly low regarding \u0022misaligned\u0022 hints\u2014such as grader hacking or utilizing unethically obtained information\u2014where Claude 3.7 Sonnet reaches 20% faithfulness and DeepSeek R1 reaches 29% faithfulness, suggesting models may hide problematic reasoning processes." } ] }, { "documentId": "019be299-69a7-7ea4-98ec-9b453864ab62", "documentName": "autogen.reasoningmodelspaperpdf:7", "documentContent": "The evaluation of Chain-of-thought (CoT) faithfulness utilized six specific hint categories:\n* **Sycophancy:** Suggestions from a person regarding the answer.\n* **Consistency:** The model\u0027s own previous response provided as a pre-fill.\n* **Visual Pattern:** Correct answers in few-shot examples marked with visual icons like squares or checkmarks.\n* **Metadata:** Answers embedded within XML metadata tags.\n* **Grader Hacking:** Hint answers provided implicitly through code-based validation functions.\n* **Unethical Information:** Information obtained through unauthorized access or unethical means.", "score": 0.525964498519898, "metadata": {}, "referencedDocuments": [ { "documentId": "019be299-6990-7c9e-9fcd-6c6037b03d16", "documentContent": "Chain-of-thought (CoT) faithfulness is the degree to which a large language model\u0027s (LLM) articulated reasoning accurately reflects the internal process used to reach a conclusion. Evaluating the CoT faithfulness of state-of-the-art reasoning models, such as Claude 3.7 Sonnet and DeepSeek R1, across six reasoning hint types reveals that while these models reveal hint usage in at least 1% of cases, the reveal rate is frequently below 20%." }, { "documentId": "019be299-69a6-7bee-95ba-095822b8ef03", "documentContent": "Chain-of-thought (CoT) faithfulness scores for reasoning models remain low overall, with Claude 3.7 Sonnet averaging 25% and DeepSeek R1 averaging 39%. These scores are particularly low regarding \u0022misaligned\u0022 hints\u2014such as grader hacking or utilizing unethically obtained information\u2014where Claude 3.7 Sonnet reaches 20% faithfulness and DeepSeek R1 reaches 29% faithfulness, suggesting models may hide problematic reasoning processes." } ] } ] }
Post/api/v1/answerAnswer generation
Answer generation
Searches one or more RAG collections, then asks a model to answer using the retrieved documents and returns both the answer and source results.
POST /api/v1/answerHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.collectionsarrayRequired
Collection UUIDs to search.
- $.termsstring | array
Search string or strings. Required unless term or prompt is supplied.
- $.termstring | array
Compatibility alias for terms.
- $.promptstring | array
Compatibility alias for terms.
- $.topinteger
Optional maximum number of results.
- $.minScorenumber
Optional minimum similarity score.
- $.rerankerstring
Optional reranker identifier.
- $.includeReferencesboolean
Includes referenced document chunks when true.
Request examples:
Answer-generation payload. Accepts the same retrieval fields as Semantic search; the retrieved documents are provided to the answer model as references.
{ "terms": [ "What is the capital of France?" ], "collections": [ "0198683a-2b6d-7066-9598-6ea119c219f2" ], "top": 10, "minScore": 0.7, "includeReferences": true }
Responses:
- 200
Generated answer plus the retrieved documents used as reference material.
{ "message": null, "data": { "answer": "The capital of France is Paris.", "queryResults": [ { "documentId": "...", "documentName": "...", "documentContent": "...", "score": 0.8, "metadata": {}, "referencedDocuments": [ ] } ] } }
Post/api/v1/generations/rerankRerank documents
Rerank documents
Ranks supplied document strings with the selected reranker.
POST /api/v1/generations/rerankHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.documentsarrayRequired
Non-empty document strings to rank.
- $.querystringRequired
Query used to rank the documents.
- $.modelstring
Optional reranker identifier.
- $.top_ninteger
Optional maximum number of ranked documents to return.
- $.min_scorenumber
Optional minimum relevance score.
Request examples:
Reranking payload.
{ "query": "What is the capital of France?", "documents": [ "Paris is the capital of France.", "London is the capital of England.", "Berlin is the capital of Germany." ], "top_n": 3, "min_score": 0.4 }
Responses:
- 200
Returns results ordered by the selected reranker.
{ "id": "req_b7336yqk4km8zek1u9xginoojc", "results": [ { "index": 0, "relevance_score": 1, "document": { "text": "Paris is the capital of France." } } ] } - 400
The model is unknown, unavailable for autonomous use, or the request exceeds its declared limits.
- 429
The account's reranking quota or Reflex token rate limit was exceeded.
- 503
The selected reranker has no inference capacity available.
Post/api/v1/generations/segmentSegment text
Segment text
Splits supplied document strings into semantically cohesive segments for embedding and RAG ingestion.
POST /api/v1/generations/segmentHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.documentsarrayRequired
Non-empty document strings to segment.
- $.sanitizeboolean
Optional text sanitization flag. Skip possible segments or documents that are better left out of the RAG.
Request examples:
Text-segmentation payload.
{ "documents": [ "AIVAX indexes documents with embeddings.\nSemantic search retrieves the most relevant passages.\nReranking can refine their order." ], "sanitize": false }
Responses:
- 200
Returns the segments for each input document.
{ "message": null, "data": { "message": null, "data": { "result": [ { "index": 0, "count": 2, "segments": [ "AIVAX indexes documents with embeddings.\nSemantic search retrieves the most relevant passages.", "Reranking can refine their order." ] } ] } } } - 400
The request body is malformed or a required field has an invalid type.
- 401
The API key is missing or invalid.
- 403
The endpoint was called with a public API key.
- 429
The account's text-segmentation document quota was exceeded.
Web Chat Client
Get/api/v1/public/chat-clients/<access-key>Get Session Info
Get Session Info
Retrieves information about the current session, including messages, client configuration, and culture settings.
GET /api/v1/public/chat-clients/<access-key>Responses:
- 200
The session information.
{ "message": null, "data": { "messages": [ { "role": "user", "content": "Hello!", "message_id": "msg_abc123" }, { "role": "assistant", "content": "Hi there!", "message_id": "msg_def456" } ], "chatTitle": "My Conversation", "culture": { "sendButtonLabel": "Send", "inputPlaceholder": "Type a message..." }, "client": { "customScripts": null, "customStyles": null, "helloLabel": "Welcome!", "helloSubLabel": "How can I help?", "logoImageUrl": "https://example.com/logo.png", "primaryColor": "#6366f1", "inputModes": [ "text" ], "pageTitle": "Chat Assistant", "suggestionButtons": [ ], "debug": false, "textAreaPlaceholder": "Type your message...", "audioSynthesisEnabled": true }, "chatCreationData": null } } - 422
The client is not available.
Post/api/v1/public/chat-clients/<access-key>/retryRetry Last Message
Retry Last Message
Removes all messages after the last user message, allowing the user to retry the conversation from that point.
POST /api/v1/public/chat-clients/<access-key>/retryResponses:
- 204
The session was reset to the last user message.
- 400
The session does not contain any messages or user messages.
- 422
The client is not available.
Post/api/v1/public/chat-clients/<access-key>/promptSend Prompt
Send Prompt
Sends a prompt to the AI gateway and returns the completion result synchronously.
POST /api/v1/public/chat-clients/<access-key>/promptPath parameters:
- access-keystring
Access key of the public chat-client session.
Request parameters:
- $.promptstring | object | arrayRequired
Text (converted to a user message), one OpenAI-compatible message, or an ordered array of messages. At least one message must contain content or tool calls. Messages are added after the existing session history for inference.
Examples:
Multimodal prompt
User prompt containing text and an image URL.
{ "prompt": { "role": "user", "content": [ { "type": "text", "text": "Describe this image." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png", "detail": "auto" } } ] } } - $.prompt.rolestring
For message objects, use user for user input, assistant for tool-call messages, or tool for tool results. Also applies to each message in an array.
- $.prompt.contentstring | array
Message text or OpenAI-compatible multimodal content parts. For tool results, provide the result as text. Also applies to each message in an array.
- $.prompt.tool_callsarray
OpenAI-compatible tool calls on an assistant message, with id, type=function and function containing name and JSON-encoded arguments.
- $.prompt.tool_call_idstring
For a tool result, the matching assistant tool-call identifier. Also applies to each message in an array.
- $.prompt.namestring
Function name for a tool result. Also applies to each message in an array.
- $.commitboolean
Defaults to true. Saves submitted and generated messages to the session. Set false to run against the existing history without saving this turn. Inference usage and tool side effects still occur; this is not a dry run.
- $.instructionsstring | array
Additional context for this inference only, appended after the session context and fetched external context. An array of strings is joined with blank lines. Does not replace or persist as the session extraContext.
Request examples:
The prompt message to send.
{ "prompt": { "role": "user", "content": "What is the capital of France?" } }Text prompt with per-inference context, without committing the turn.
{ "prompt": "Summarize the current order.", "commit": false, "instructions": [ "The current order contains two books.", "Answer in one sentence." ] }Providing client-side tool result. After a committed tool call, submit its result using the matching tool_call_id. Use an array for multiple results. If the previous call used commit=false, include its assistant tool-call message before the tool results because it was not saved.
{ "prompt": [ { "role": "tool", "tool_call_id": "<tool-call-id>", "name": "get_weather", "content": "{\"city\":\"Paris\",\"temperatureC\":22}" } ], "commit": true }
Responses:
- 200
Simple completion result. Returns completionText (text from the last generated assistant message, falling back to accumulated inference text if that message is absent or its text is empty), optional reasoning, client-side toolCalls, usage and createdMessages (new messages only, in generation order).
{ "message": null, "data": { "completionText": "The capital of France is Paris.", "reasoning": null, "toolCalls": [ ], "usage": { "promptTokens": 15, "completionTokens": 8, "totalTokens": 23 }, "createdMessages": [ { "role": "assistant", "content": "The capital of France is Paris." } ] } } - 402
Account balance is zero or negative.
- 422
The client is not available.
- 200
Client-side tool calls. Execute the requested function in your application, then submit its result in a new prompt request. Top-level toolCalls uses the client-call format; createdMessages uses OpenAI-compatible message format.
{ "message": null, "data": { "completionText": "", "reasoning": null, "toolCalls": [ { "id": "\u003Ctool-call-id\u003E", "functionName": "get_weather", "contents": "{\u0022city\u0022:\u0022Paris\u0022}", "isProtocolFunction": false } ], "usage": { "promptTokens": 40, "completionTokens": 12, "totalTokens": 52 }, "createdMessages": [ { "role": "assistant", "content": "", "tool_calls": [ { "id": "\u003Ctool-call-id\u003E", "type": "function", "function": { "name": "get_weather", "arguments": "{\u0022city\u0022:\u0022Paris\u0022}" } } ] } ] } } - 200
Providing client-side tool result. Response after submitting the matching tool result shown in the request examples. The submitted result is not repeated in createdMessages.
{ "message": null, "data": { "completionText": "It is 22 \u00B0C in Paris.", "reasoning": null, "toolCalls": [ ], "usage": { "promptTokens": 65, "completionTokens": 10, "totalTokens": 75 }, "createdMessages": [ { "role": "assistant", "content": "It is 22 \u00B0C in Paris." } ] } } - 200
Multiple created messages (server-side tool calling). The server executes the tool and continues inference. completionText contains the final assistant reply, without the earlier announcement. No client-side execution is requested; createdMessages preserves the assistant tool call, tool result and final reply. Optional per-message metadata is omitted from these examples.
{ "message": null, "data": { "completionText": "It is 22 \u00B0C in Paris.", "reasoning": null, "toolCalls": [ ], "usage": { "promptTokens": 105, "completionTokens": 22, "totalTokens": 127 }, "createdMessages": [ { "role": "assistant", "content": "I will search the weather data now.", "tool_calls": [ { "id": "\u003Ctool-call-id\u003E", "type": "function", "function": { "name": "get_weather", "arguments": "{\u0022city\u0022:\u0022Paris\u0022}" } } ] }, { "role": "tool", "tool_call_id": "\u003Ctool-call-id\u003E", "name": "get_weather", "content": "{\u0022city\u0022:\u0022Paris\u0022,\u0022temperatureC\u0022:22}" }, { "role": "assistant", "content": "It is 22 \u00B0C in Paris." } ] } }
Get/api/v1/public/chat-clients/<access-key>/transcript.jsonDownload Session Transcript
Download Session Transcript
Downloads the session messages, context, and metadata as a JSON file.
GET /api/v1/public/chat-clients/<access-key>/transcript.jsonResponses:
- 200
The transcript JSON file.
{ "message": null, "data": { "messages": [ { "role": "user", "content": "Hello!" }, { "role": "assistant", "content": "Hi! How can I help you?" } ], "context": "Additional context for the session.", "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metadata": {} } } - 422
The client is not available.
Platform
Get/api/v1/platform/searchSearch Platform
Search Platform
Lists account-owned RAG collections, AI Gateways, chat clients, batch workflows and jobs, plus integrated models for client-side search.
GET /api/v1/platform/searchHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
{ "message": null, "data": [ { "id": string, "type": string, "title": string, "description": string, "url": string }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" } } } }
Notifications
Get/api/v1/notificationsList Notifications
List Notifications
Lists notifications for the authenticated account from newest to oldest.
GET /api/v1/notificationsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
Minimal notification summaries.
{ "message": null, "data": [ { "id": "019f66a9-4f81-7d41-add7-569eac61bb63", "createdAt": "2026-07-15T12:00:00", "type": "LowBalanceNotification", "subject": "AIVAX account balance alert", "message": "Your current balance is below the configured threshold.", "readAt": null } ] }
Get/api/v1/notifications/unread/countCount Unread Notifications
Count Unread Notifications
Counts notifications that have not been read by the authenticated account.
GET /api/v1/notifications/unread/countHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
Unread notification count.
{ "message": null, "data": { "count": 3 } }
Memories
Get/api/v1/memoriesList Memories
List Memories
Lists persisted memories stored for the authenticated account, optionally filtered by text and memory format.
GET /api/v1/memoriesHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- filterstring
Optional filter applied to memory id, content, and external user id.
- formatstring
Optional format filter. Accepted values: Text or DateReminder.
- gatewayIdstring
Optional gateway filter. Use a gateway UUID or 'shared' for memories without a gateway link.
Responses:
- 200
The matching memory entries.
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", "externalUserId": string, "content": string?, "format": "Text", "gateway": { // UUID/GUID string "id": "uuid", "name": string, "modelName": string, "slug": string }? }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "externalUserId": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "format": { "type": "string", "enum": [ "Text", "DateReminder" ] }, "gateway": { "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "modelName": { "type": "string" }, "slug": { "type": "string" } }, "type": [ "object", "null" ] } } } }
Delete/api/v1/memoriesDelete Memories
Delete Memories
Deletes either one persisted memory by id or all memories for an external user id and format.
DELETE /api/v1/memoriesHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- iduuid
Deletes a single memory by its unique identifier. Cannot be combined with externalUserId.
- externalUserIdstring
Deletes memories associated with the specified external user identifier. Cannot be combined with id.
- formatstring
Required when deleting by externalUserId. Accepted values: Text or DateReminder.
Responses:
- 200
The memory or memories were deleted successfully.
{ "message": null, "data": { "message": "Memories deleted successfully.", "removedCount": 2, "externalUserId": "customer-123", "format": "Text" } } - 400
The query string is invalid, such as when neither or both id and externalUserId are provided, or the format is invalid.
- 404
The requested memory id does not exist for the authenticated account.
Get/api/v1/memories/<id>Get Memory
Get Memory
Returns one persisted memory with full content, external user id, format and expiration time.
GET /api/v1/memories/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the memory to retrieve.
Responses:
- 200
Persisted memory details.
{ "message": null, "data": { // UUID/GUID string "id": "uuid", "externalUserId": string, "content": string, "format": "Text", // ISO 8601 date-time string "createdAt": "date-time", // ISO 8601 date-time string "expiresAt": "date-time", "gateway": { // UUID/GUID string "id": "uuid", "name": string, "modelName": string, "slug": string }? } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "externalUserId": { "type": "string" }, "content": { "type": "string" }, "format": { "type": "string", "enum": [ "Text", "DateReminder" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "gateway": { "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "modelName": { "type": "string" }, "slug": { "type": "string" } }, "type": [ "object", "null" ] } } } - 404
The memory was not found for the authenticated account.
Get/api/v1/memories/generate/migrationGenerate Memory Migration Prompt
Generate Memory Migration Prompt
Builds a prompt containing the authenticated account's persisted memory and scheduled-message context for one external user.
GET /api/v1/memories/generate/migrationHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- externalUserIdstringRequired
External user identifier whose persisted context will be included.
Responses:
- 200
Migration prompt containing the external user's persisted context.
{ "message": null, "data": { "migrationPrompt": "## Active memory data\n- Type=\u0027Text\u0027 Data=\u0027...\u0027" } } - 400
The externalUserId query parameter is missing or invalid.
Information
Get/api/v1/information/balanceGet Account Balance
Get Account Balance
Returns billing and quota status for the authenticated account, including balance, last-24-hour usage, plan, storage usage, subscription usage and plan limits.
GET /api/v1/information/balanceHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
Current balance, recent usage, storage usage, subscription consumption and plan limits.
{ "message": null, "data": { "balance": 12.5, "usage24h": 0.42, "plan": "Pro", "storageUsage": 1048576, "subscriptionModelUsage": { "plan": "Pro", "consumptions": [ { "type": "InferenceSixHours", "name": "6-hour model usage", "usedPercent": 1.8, "resetAt": "2026-05-18T12:00:00Z", "isExhausted": false, "details": [ { "usageName": "gpt-4o", "usageSharePercent": 100 } ] } ] }, "planLimits": { "includesSubscriptionModels": true, "includedStorage": 1073741824 } } } - 401
Missing or invalid Authorization header.
Get/api/v1/information/usage/monthly-reportGet Monthly Usage Report
Get Monthly Usage Report
Returns monthly usage insights and top-cost model, resource and SKU tables for the authenticated account.
GET /api/v1/information/usage/monthly-reportHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- monthstring
Reporting month in YYYY-MM format.
Responses:
- 200
Monthly usage report with top 10 rankings and an Other remainder item when needed.
{ "message": null, "data": { // ISO 8601 date-time string "generatedAt": "date-time", // ISO 8601 date-time string "periodStart": "date-time", // ISO 8601 date-time string "periodEnd": "date-time", "tokenVolume": number, "inferenceCost": number, "ragCost": number, "serviceCost": number, "totalCost": number, "models": [ { "name": string, "cost": number }, ... ], "resources": [ { "name": string, "type": string, "cost": number }, ... ], "skus": [ { "name": string, "quantity": number, "cost": number }, ... ] } }{ "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "periodStart": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "periodEnd": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "tokenVolume": { "type": "number" }, "inferenceCost": { "type": "number" }, "ragCost": { "type": "number" }, "serviceCost": { "type": "number" }, "totalCost": { "type": "number" }, "models": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "cost": { "type": "number" } } } }, "resources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "cost": { "type": "number" } } } }, "skus": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "number" }, "cost": { "type": "number" } } } } } } - 401
Missing or invalid Authorization header.
Get/api/v1/information/rerankers-models.jsonGet Reranker Models
Get Reranker Models
Returns the current reranker catalog, pricing descriptions, autonomous-use capability, technical limits, and default selection.
GET /api/v1/information/rerankers-models.jsonResponses:
- 200
Available rerankers and the explicit option to disable reranking.
{ "message": null, "data": [ { "name": "@aivax/reflex-v1", "description": "AIVAX low-latency semantic reranker with bounded lexical evidence and account-scoped document caching.", "pricingDescription": "$0.015/mtokens (cache miss)\n$0.003/mtokens (cache hit)", "autonomousUse": true, "technicalInformation": { "contextSize": 1948, "maxDocuments": 10000 }, "isDefault": true } ] }
Get/api/v1/information/audio-transcription-models.jsonGet Audio Transcription Models
Get Audio Transcription Models
Returns the speech-to-text models available through the audio transcription endpoint, including published duration-based pricing.
GET /api/v1/information/audio-transcription-models.jsonResponses:
- 200
Available speech-to-text models and supported audio formats.
Agentic Tests
Get/api/v1/agentic-testsList Agentic Tests
List Agentic Tests
Lists persisted Agentic Tests owned by the authenticated account, optionally filtered by name and gateway. Each entry includes its schedule and latest run summary with execution state and judge outcome.
GET /api/v1/agentic-testsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- searchstring
Optional case-insensitive test-name search.
- gatewaystring
Optional exact gateway identifier, slug, or integrated model name.
Responses:
- 200
Agentic Test summaries.
{ "message": null, "data": { "data": [ { "id": "019...", "name": "Checkout regression", "gateway": "checkout-gateway", "enabled": true, "cron": null, "next_run_at": null, "created_at": "2026-08-16T03:00:00", "updated_at": "2026-08-16T03:00:00", "latest_run": null } ] } }
Post/api/v1/agentic-testsCreate Agentic Test
Create Agentic Test
Creates a reusable Agentic Test definition for a gateway or integrated model. A configured cron expression must use standard five-field syntax and cannot run more often than every five minutes.
POST /api/v1/agentic-testsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.namestringRequired
Human-readable test name. Maximum length: 200 characters.
- $.gatewaystringRequired
AI Gateway slug, gateway identifier, or integrated model name to test. Maximum length: 200 characters.
- $.goalstring | object | arrayRequired
Goal pursued by the simulated user and evaluated by the judge. Accepts text, one multimodal message part, or an array of message parts.
- $.validation_criteriastring | object | array | null
Additional success criteria visible only to the judge. Accepts text, one multimodal message part, or an array of message parts. Defaults to null.
- $.startarray
Initial OpenAI-compatible conversation messages supplied before simulation begins. Defaults to an empty array.
- $.max_turnsinteger
Maximum simulated user turns, from 2 to 64. Defaults to 10.
- $.minimum_turnsinteger
First turn on which the simulated user may end the conversation, from 1 to max_turns - 1. Defaults to 1.
- $.allow_user_exitboolean
Whether the simulated user may end the conversation after minimum_turns. Defaults to true.
- $.judge_start_turninteger
First turn evaluated by the judge, from 1 to max_turns - 1. Defaults to 1.
- $.loss_thresholdnumber
Score below which consecutive judge evaluations contribute to failure, from 0.01 to 0.99. Must be more than 0.1 below base_threshold. Defaults to 0.2.
- $.base_thresholdnumber
Score at or above which the goal is achieved, from 0.01 to 0.99. Must be more than 0.1 above loss_threshold. Defaults to 0.9.
- $.profilestring
Simulator and judge model profile: low, medium, or high. Defaults to medium.
- $.user_samplingobject
Optional simulated-user sampling configuration.
- $.user_sampling.top_knumber
Maximum option-selection range used by the simulated-user sampler, from 0 to 2. Defaults to 0.4.
- $.user_sampling.max_decaynumber
Maximum probability decay used by the simulated-user sampler, from 0 to 1. Defaults to 0.02.
- $.metadataobject
String key/value metadata forwarded to gateway inference. Defaults to an empty object.
- $.resourcesarray
External context resources. Accepts at most 16 items and defaults to an empty array.
Examples:
Inline context for internal evaluation
Resolves inline text once at run startup and exposes it only to the simulated user and judge.
[ { "type": "Text", "hook": "OnStart", "visibility": "Internal", "cacheDuration": 900, "data": "The customer has a 14-day refund window." } ]Fresh remote context for the gateway
Fetches the URL before every turn, bypasses cache, and exposes the result only to the tested gateway.
[ { "type": "RemoteResource", "hook": "OnTurn", "visibility": "Gateway", "cacheDuration": 0, "data": "https://example.com/current-inventory" } ]Shared cached remote context
Fetches the URL at run startup and exposes the result to the simulated user, judge, and tested gateway. The remote response may be reused for up to six hours.
[ { "type": "RemoteResource", "hook": "OnStart", "visibility": "Both", "cacheDuration": 21600, "data": "https://example.com/refund-policy" } ] - $.resources[].typestring
Resource source: Text for inline content or RemoteResource for an HTTP or HTTPS URL. Defaults to Text.
- $.resources[].hookstring
Resolution lifecycle: OnStart resolves once when the run starts; OnTurn resolves once before each turn. Defaults to OnStart.
- $.resources[].visibilitystring
Recipients: Internal exposes the resource only to the simulated user and judge; Gateway exposes it only to the tested gateway; Both exposes it to all three. Defaults to Internal.
- $.resources[].cacheDurationinteger
Remote-resource cache duration in seconds, from 0 to 21600. Zero disables caching between resolutions. Defaults to 900.
- $.resources[].datastring
Required non-empty inline text or remote HTTP/HTTPS URL, according to type.
- $.external_user_idstring | null
Optional external user identifier forwarded to gateway usage and conversation attribution. Maximum length: 200 characters. Defaults to null.
- $.hooksarray
Validation callbacks for persisted runs. Accepts at most 16 items and defaults to an empty array.
- $.hooks[].eventstring
Required callback event: before-test, after-test, before-inference, after-inference, or context-changed. before-inference and after-inference require an AI Gateway rather than an integrated model.
- $.hooks[].urlstring
Required public HTTP or HTTPS callback URL. Local and private addresses are rejected. Maximum length: 2048 characters.
- $.cronstring | null
Optional standard five-field cron expression. Consecutive occurrences must be at least five minutes apart. Defaults to null.
- $.enabledboolean
Whether scheduled runs are enabled. Defaults to true.
- $.notification_thresholdinteger
Consecutive failed runs required before a failure notification is created. Minimum: 1. Defaults to 1.
- $.recovery_notificationboolean
Whether a successful run after failures creates a recovery notification. Defaults to true.
Request examples:
Agentic Test definition. Goal is shared with the simulated user and judge; validation_criteria is visible only to the judge. Both may be a string, message part, or list of message parts. Resources accepts up to 16 Text or RemoteResource objects, resolved OnStart or OnTurn and visible to Internal generators, the Gateway, or Both. cacheDuration is expressed in seconds from 0 to 21600.
{ "name": "Checkout regression", "gateway": "checkout-gateway", "goal": "Complete checkout successfully", "validation_criteria": "The assistant must confirm the order total before checkout.", "start": [], "resources": [ { "type": "Text", "hook": "OnStart", "visibility": "Internal", "cacheDuration": 900, "data": "The customer has a 14-day refund window." } ], "max_turns": 10, "minimum_turns": 1, "allow_user_exit": true, "judge_start_turn": 1, "loss_threshold": 0.2, "base_threshold": 0.9, "profile": "medium", "user_sampling": { "top_k": 0.4, "max_decay": 0.02 }, "metadata": {}, "hooks": [ { "event": "before-test", "url": "https://validator.example/hooks/agentic-tests" }, { "event": "after-test", "url": "https://validator.example/hooks/agentic-tests" } ], "external_user_id": null, "cron": null, "enabled": true, "notification_threshold": 1, "recovery_notification": true }
Responses:
- 201
The Agentic Test was created. The response contains its complete persisted definition.
- 400
The payload, gateway, thresholds, profile, sampling values, or cron expression is invalid.
Get/api/v1/agentic-tests/<id>View Agentic Test
View Agentic Test
Returns the complete definition, schedule, notification state, and latest run for one Agentic Test.
GET /api/v1/agentic-tests/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
Responses:
- 200
Complete Agentic Test details.
- 404
The test does not exist or is not owned by the authenticated account.
Patch/api/v1/agentic-tests/<id>Update Agentic Test
Update Agentic Test
Partially updates an Agentic Test. Omitted fields retain their current values; changing scheduling fields recalculates the next run time.
PATCH /api/v1/agentic-tests/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
Request parameters:
- $.namestring
Replacement human-readable test name. Maximum length: 200 characters.
- $.gatewaystring
Replacement AI Gateway slug, gateway identifier, or integrated model name. Maximum length: 200 characters.
- $.goalstring | object | array
Replacement goal pursued by the simulated user and evaluated by the judge.
- $.validation_criteriastring | object | array
Replacement criteria visible only to the judge.
- $.startarray
Replacement initial OpenAI-compatible conversation messages.
- $.max_turnsinteger
Replacement maximum simulated user turns, from 2 to 64.
- $.minimum_turnsinteger
Replacement first turn on which the simulated user may exit, from 1 to max_turns - 1.
- $.allow_user_exitboolean
Replacement setting controlling whether the simulated user may exit after minimum_turns.
- $.judge_start_turninteger
Replacement first turn evaluated by the judge, from 1 to max_turns - 1.
- $.loss_thresholdnumber
Replacement loss threshold, from 0.01 to 0.99 and more than 0.1 below base_threshold.
- $.base_thresholdnumber
Replacement success threshold, from 0.01 to 0.99 and more than 0.1 above loss_threshold.
- $.profilestring
Replacement simulator and judge model profile: low, medium, or high.
- $.user_samplingobject
Replacement simulated-user sampling configuration.
- $.user_sampling.top_knumber
Maximum option-selection range from 0 to 2.
- $.user_sampling.max_decaynumber
Maximum probability decay from 0 to 1.
- $.metadataobject
Replacement string key/value metadata forwarded to gateway inference.
- $.resourcesarray
Replacement list of external context resources. Accepts at most 16 items; supplying it replaces the complete list.
Examples:
Replace with inline and remote resources
Replaces the complete resource list with one internal startup context and one gateway-only per-turn URL.
[ { "type": "Text", "hook": "OnStart", "visibility": "Internal", "cacheDuration": 900, "data": "The customer is eligible for priority support." }, { "type": "RemoteResource", "hook": "OnTurn", "visibility": "Gateway", "cacheDuration": 0, "data": "https://example.com/current-account-state" } ] - $.resources[].typestring
Resource source: Text or RemoteResource. Defaults to Text when omitted from an item.
- $.resources[].hookstring
Resolution lifecycle: OnStart or OnTurn. Defaults to OnStart when omitted from an item.
- $.resources[].visibilitystring
Recipients: Internal, Gateway, or Both. Defaults to Internal when omitted from an item.
- $.resources[].cacheDurationinteger
Remote-resource cache duration in seconds, from 0 to 21600. Zero disables caching between resolutions. Defaults to 900 when omitted from an item.
- $.resources[].datastring
Required non-empty inline text or remote HTTP/HTTPS URL, according to type.
- $.external_user_idstring
Replacement external user identifier forwarded to gateway usage and conversation attribution. Maximum length: 200 characters.
- $.hooksarray
Replacement validation callback list. Accepts at most 16 items.
- $.hooks[].eventstring
Required callback event: before-test, after-test, before-inference, after-inference, or context-changed. before-inference and after-inference require an AI Gateway rather than an integrated model.
- $.hooks[].urlstring
Required public HTTP or HTTPS callback URL. Local and private addresses are rejected.
- $.cronstring | null
Replacement standard five-field cron expression. Consecutive occurrences must be at least five minutes apart; null disables scheduling.
- $.enabledboolean
Replacement scheduled-run enabled state.
- $.notification_thresholdinteger
Replacement consecutive-failure notification threshold. Minimum: 1.
- $.recovery_notificationboolean
Replacement recovery-notification setting.
Request examples:
Partial Agentic Test definition containing only fields to change. Supplying resources replaces the complete resource list.
{ "resources": [ { "type": "RemoteResource", "hook": "OnTurn", "visibility": "Both", "cacheDuration": 900, "data": "https://example.com/refund-policy" } ] }
Responses:
- 200
The Agentic Test was updated.
- 400
One or more supplied fields are invalid.
- 404
The test does not exist or is not owned by the authenticated account.
Delete/api/v1/agentic-tests/<id>Delete Agentic Test
Delete Agentic Test
Permanently deletes one Agentic Test owned by the authenticated account. Its runs are deleted through the configured relationship.
DELETE /api/v1/agentic-tests/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
Responses:
- 204
The Agentic Test was deleted.
- 404
The test does not exist or is not owned by the authenticated account.
Post/api/v1/generations/validationsEvaluate Agentic Test
Evaluate Agentic Test
Runs an ephemeral Agentic Test against an AI gateway or integrated model and streams progress as server-sent events. Direct evaluations are not stored as Agentic Test cases or runs. The validations route is retained as a compatibility alias.
POST /api/v1/generations/validationsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.modelstringRequired
AI Gateway slug, gateway identifier, or integrated model name to test.
- $.goalstring | object | arrayRequired
Goal pursued by the simulated user and evaluated by the judge. Accepts text, one multimodal message part, or an array of message parts.
- $.validation_criteriastring | object | array | null
Additional success criteria visible only to the judge. Defaults to null.
- $.startarray
Initial OpenAI-compatible conversation messages supplied before simulation begins. Defaults to an empty array.
Examples:
Initial conversation
Starts the evaluation with an existing OpenAI-compatible conversation.
{ "model": "checkout-gateway", "goal": "Complete checkout successfully", "start": [ { "role": "assistant", "content": "Welcome. How can I help with your order?" }, { "role": "user", "content": "I want to complete checkout for the items in my cart." } ] } - $.max_turnsinteger
Maximum simulated user turns, from 2 to 64. Defaults to 10.
- $.minimum_turnsinteger
First turn on which the simulated user may end the conversation, from 1 to max_turns - 1. Defaults to 1.
- $.allow_user_exitboolean
Whether the simulated user may end the conversation after minimum_turns. Defaults to true.
- $.judge_start_turninteger
First turn evaluated by the judge, from 1 to max_turns - 1. Defaults to 1.
- $.loss_thresholdnumber
Score below which consecutive judge evaluations contribute to failure, from 0.01 to 0.99. Must be more than 0.1 below base_threshold. Defaults to 0.2.
- $.base_thresholdnumber
Score at or above which the goal is achieved, from 0.01 to 0.99. Must be more than 0.1 above loss_threshold. Defaults to 0.9.
- $.metadataobject
String key/value metadata forwarded to gateway inference. Defaults to an empty object.
- $.resourcesarray
Optional external context resources. Accepts at most 16 items.
Examples:
Inline context for internal evaluation
Resolves inline text once when the evaluation starts and exposes it only to the simulated user and judge.
[ { "type": "Text", "hook": "OnStart", "visibility": "Internal", "cacheDuration": 900, "data": "The customer has a 14-day refund window." } ]Fresh remote context for the gateway
Fetches the URL before every turn, bypasses cache, and exposes the result only to the tested gateway.
[ { "type": "RemoteResource", "hook": "OnTurn", "visibility": "Gateway", "cacheDuration": 0, "data": "https://example.com/current-inventory" } ]Shared cached remote context
Fetches the URL once at evaluation startup and exposes the result to all inference participants with a six-hour cache.
[ { "type": "RemoteResource", "hook": "OnStart", "visibility": "Both", "cacheDuration": 21600, "data": "https://example.com/refund-policy" } ] - $.resources[].typestring
Resource source: Text for inline content or RemoteResource for an HTTP or HTTPS URL. Defaults to Text.
- $.resources[].hookstring
Resolution lifecycle: OnStart resolves once when the evaluation starts; OnTurn resolves once before each turn. Defaults to OnStart.
- $.resources[].visibilitystring
Recipients: Internal exposes the resource only to the simulated user and judge; Gateway exposes it only to the tested gateway; Both exposes it to all three. Defaults to Internal.
- $.resources[].cacheDurationinteger
Remote-resource cache duration in seconds, from 0 to 21600. Zero disables caching between resolutions. Defaults to 900.
- $.resources[].datastring
Required non-empty inline text or remote HTTP/HTTPS URL, according to type.
- $.profilestring
Simulator and judge model profile: low, medium, or high. Defaults to medium.
- $.external_user_idstring | null
External user identifier forwarded to gateway usage and conversation attribution. Maximum length: 200 characters. Defaults to null.
- $.userstring | null
Compatibility alias used only when external_user_id is omitted.
- $.streamboolean
Accepted for OpenAI compatibility; this endpoint always streams server-sent events regardless of the supplied value.
- $.user_samplingobject
Simulated-user sampling configuration.
- $.user_sampling.top_knumber
Maximum option-selection range used by the simulated-user sampler, from 0 to 2. Defaults to 0.4.
- $.user_sampling.max_decaynumber
Maximum probability decay used by the simulated-user sampler, from 0 to 1. Defaults to 0.02.
Request examples:
Direct Agentic Test parameters. Goal is shared with the simulated user and judge; validation_criteria is visible only to the judge. Resources accepts up to 16 Text or RemoteResource objects. Each resource controls when it is resolved, which inference participants receive it, and how long remote content is cached.
{ "model": "checkout-gateway", "goal": "Complete checkout successfully", "validation_criteria": "The assistant must confirm the order total before checkout.", "start": [], "resources": [ { "type": "Text", "hook": "OnStart", "visibility": "Internal", "cacheDuration": 900, "data": "The customer has a 14-day refund window." } ], "max_turns": 10, "minimum_turns": 1, "allow_user_exit": true, "judge_start_turn": 1, "loss_threshold": 0.2, "base_threshold": 0.9, "profile": "medium", "user_sampling": { "top_k": 0.4, "max_decay": 0.02 }, "metadata": {}, "external_user_id": "customer-123", "stream": true }
Responses:
- 200
A text/event-stream response containing chat.*, usage_updated, chat.validation.end, or unhandled_error events.
- 400
The model, goal, thresholds, profile, sampling values, or initial conversation is invalid.
- 402
The authenticated account does not have enough operating balance.
Post/api/v1/agentic-tests/<id>/runsRun Agentic Test
Run Agentic Test
Creates a pending run from the current Agentic Test definition. The background runner executes it according to the account concurrency limit.
POST /api/v1/agentic-tests/<id>/runsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
Responses:
- 202
The run was queued.
{ "message": null, "data": { "id": "019...", "test_id": "019...", "state": "pending", "created_at": "2026-08-16T03:00:00", "started_at": null, "finished_at": null, "score": null, "cost": 0, "error": null, "external_user_id": null } } - 404
The test does not exist or is not owned by the authenticated account.
Get/api/v1/agentic-tests/<id>/runsList Agentic Test Runs
List Agentic Test Runs
Lists retained runs for one Agentic Test in reverse creation order, including execution state and judge outcome.
GET /api/v1/agentic-tests/<id>/runsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
Query parameters:
- statestring
Optional run-state filter: pending, running, succeeded, failed, or cancelled.
- limitinteger
Maximum number of runs to return. Defaults to 50 and is capped at 100.
- offsetinteger
Number of runs to skip. Defaults to zero.
Responses:
- 200
Run summaries for the requested test.
- 404
The test does not exist or is not owned by the authenticated account.
Get/api/v1/agentic-tests/<id>/runs/<run-id>View Agentic Test Run
View Agentic Test Run
Returns an exportable run document with outcome, cost, errors, timestamped user and assistant messages, judge opinions, and per-message token usage.
GET /api/v1/agentic-tests/<id>/runs/<run-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
- run-iduuid
Run identifier.
Responses:
- 200
Complete run details. Conversation roles may be user, assistant, or judge.
- 404
The test or run does not exist or is not owned by the authenticated account.
Post/api/v1/agentic-tests/<id>/runs/<run-id>/cancelCancel Agentic Test Run
Cancel Agentic Test Run
Cancels a pending run immediately or signals cooperative cancellation for a running test. Terminal runs remain unchanged.
POST /api/v1/agentic-tests/<id>/runs/<run-id>/cancelHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Agentic Test identifier.
- run-iduuid
Run identifier.
Responses:
- 200
The current run summary after applying the cancellation request.
- 404
The test or run does not exist or is not owned by the authenticated account.
Generations
Post/api/v1/generations/speechGenerate speech
Generate speech
Synthesizes speech from text. Set raw to true to receive binary audio; otherwise the response contains base64-encoded audio in the standard JSON envelope.
POST /api/v1/generations/speechHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
Speech synthesis parameters.
{ "model": "grokvoice", "input": "Hello!", "voice": "alloy", "format": "wav", "raw": false }
Responses:
- 200
Generated MP3, WAV or OGG audio. When raw is false, data is base64 encoded in JSON.
{ "message": null, "data": { "format": "wav", "mimeType": "audio/wav", "data": "UklGRiQAAABXQVZFZm10..." } } - 400
The model, input, format or raw value is invalid.
- 402
The account does not have a positive balance.
- 429
A request-level rate limit was exceeded.
Post/api/v1/generations/imagesGenerate images
Generate images
Generates one to four images for each supplied prompt using the selected image model. Optional reference images are supported when the model exposes that capability. Note: it is recommended to use the long inference endpoint at https://direct.inference.aivax.net/, because this endpoint may take a while to respond for some models.
POST /api/v1/generations/imagesHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.inputstring | arrayRequired
Prompt string or non-empty prompt string array.
Examples:
Multiple prompts
Generates images for each prompt in the input array.
{ "input": [ "A kitten playing with a ball", "A lighthouse during a winter storm" ], "count": 1, "model": "wan-image-2.7-pro" } - $.countinteger
Optional number of images per prompt, from 1 to 4.
- $.modelstringRequired
Image model identifier.
- $.referenceImagesarray
Optional HTTP(S) reference image URLs.
Request examples:
Image generation parameters. Input may be one prompt or an array of prompts; each prompt generates count images.
{ "input": "A kitten playing with a ball", "count": 4, "model": "wan-image-2.7-pro", "referenceImages": [ "https://example.com/reference-1.jpg", "https://example.com/reference-2.jpg" ] }
Responses:
- 200
Generated image URLs grouped by input prompt.
{ "message": null, "data": { "message": null, "data": [ { "input": "A kitten playing with a ball", "images": [ "https://aivax-objects.example/image-1.jpg", "https://aivax-objects.example/image-2.jpg" ] } ] } } - 400
The prompt, count, model or reference images are invalid.
- 402
The account does not have a positive balance.
- 429
The image-generation or request-level rate limit was exceeded.
Post/api/v1/generations/classifyClassify documents
Classify documents
Embeds supplied documents and labels, then returns every label ordered by cosine similarity for each document.
POST /api/v1/generations/classifyHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.documentsarrayRequired
Non-empty document strings to classify.
- $.labelsarrayRequired
Non-empty labels to score against every document.
Request examples:
Document classification payload.
{ "documents": [ "Calculate the compound interest on a principal of $10,000 invested for 5 years at an annual rate of 5%, compounded quarterly", "Erklären Sie die Unterschiede zwischen Merge-Sort und Quicksort-Algorithmen in Bezug auf Zeitkomplexität, Platzkomplexität und Leistung in der Praxis.", "Write a poem about the beauty of nature and its healing power on the human soul" ], "labels": [ "Creative writing", "Complex problem", "Simple task" ] }
Responses:
- 200
Returns one result per document. Every supplied label is included and ordered from highest to lowest cosine similarity.
{ "message": null, "data": { "message": null, "data": { "results": [ { "index": 0, "document": "Calculate the compound interest on a principal of $10,000 invested for 5 years at an annual rate of 5%, compounded quarterly", "scores": [ { "label": "Complex problem", "score": 0.98828 }, { "label": "Simple task", "score": 0.45272 }, { "label": "Creative writing", "score": 0.06823 } ] } ] } } } - 400
The request body is malformed, an array is empty, or a document or label is empty.
- 401
The API key is missing or invalid.
- 403
The endpoint was called with a public API key or the account has no positive balance.
- 429
The account's text-classification quota was exceeded.
- 503
The default embedding model has no inference capacity available.
Post/api/v1/generations/teach-skillTeach skill
Teach skill
Analyzes one or more tutorial videos and returns reusable skill instructions as a structured Markdown document. Note: it is recommended to use the long inference endpoint at https://direct.inference.aivax.net/, because this endpoint may take a while to respond.
POST /api/v1/generations/teach-skillHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.videosarrayRequired
OpenAI-compatible video_url content parts.
Request examples:
Tutorial videos represented as OpenAI-compatible video_url content parts.
{ "videos": [ { "type": "video_url", "video_url": { "url": "https://example.com/tutorial.mp4" } }, { "type": "video_url", "video_url": { "url": "data:video/mp4,base64,TWFueSBoYW5kcyBtYWtlIGxpZ2h0IHdvcmsu..." } } ] }
Responses:
- 200
A JSON envelope whose data contains the generated Markdown tutorial and processed usage units.
{ "message": null, "data": { "resultText": "---\ntitle: Example tutorial\ndescription: Instructions extracted from the tutorial videos\ntags: example, tutorial\n---\n\n# Step 1 – Open the application\n\nOpen the application and navigate to the required workspace.", "usage": { "processedUnits": 1234 } } } - 400
The request is invalid or contains content other than video_url parts.
- 401
The API key is missing or invalid.
- 429
The account's applicable media-processing request limit was exceeded.
Post/api/v1/generations/descriptionsDescribe media
Describe media
Resolves each OpenAI-compatible multimodal content part into structured JSON. Audio, images, video and PDF files are processed independently and returned in input order. Note: it is recommended to use the long inference endpoint at https://direct.inference.aivax.net/, because this endpoint may take a while to respond for large files.
POST /api/v1/generations/descriptionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.inputarrayRequired
OpenAI-compatible multimodal content parts to describe.
Examples:
Image URL
Describes an image from an HTTP(S) URL.
{ "extractionGuidance": "Identify the main subject and visible text.", "input": [ { "type": "image_url", "image_url": { "url": "https://example.com/image.png", "detail": "high" } } ] }Video URL
Describes a video from an HTTP(S) URL.
{ "extractionGuidance": "Summarize the sequence of events.", "input": [ { "type": "video_url", "video_url": { "url": "https://example.com/video.mp4" } } ] } - $.presetstring
Optional processing preset: auto or high.
- $.extractionGuidancestring
Optional instruction that guides the description.
Request examples:
Multimodal content parts to resolve. The optional preset accepts 'auto' (default), which downloads remote file URLs up to 5 MB before processing, or 'high', which sends remote file URLs directly to the resolver.
{ "preset": "auto", "extractionGuidance": "Optional extraction guidance for refining extraction results.", "input": [ { "type": "input_audio", "input_audio": { "data": "base64-encoded-audio", "format": "wav" } }, { "type": "file", "file": { "filename": "document.pdf", "file_data": "https://bitcoin.org/bitcoin.pdf" } } ] }
Responses:
- 200
One resolver-generated JSON object corresponding to each input item, with a shape that depends on the content type.
{ "message": null, "data": { "message": null, "data": [ { "textContent": "The extracted PDF text.", "sections": [ ], "fileData": { "format": "PDF", "language": "English", "isUnsafe": false } } ] } } - 400
The input is missing, unsupported or contains invalid media data.
- 402
The account does not have a positive balance or has exceeded its storage quota.
- 429
A request-level or inference rate limit was exceeded.
Post/api/v1/generations/audio/transcriptionsTranscribe audio
Transcribe audio
Transcribes a base64-encoded WAV, MP3, M4A, FLAC, OGG, WebM or AAC file with an available speech-to-text model.
POST /api/v1/generations/audio/transcriptionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request parameters:
- $.modelstring
Optional speech-to-text model identifier.
- $.input_audioobjectRequired
Base64-encoded audio and its format.
- $.input_audio.datastringRequired
Base64-encoded audio bytes.
- $.input_audio.formatstringRequired
Audio format: wav, mp3, m4a, flac, ogg, webm or aac.
- $.languagestring
Optional language hint.
Request examples:
Audio transcription parameters.
{ "model": "x-ai/grok-stt-1.0", "input_audio": { "data": "UklGRiQAAABXQVZFZm10...", "format": "wav" }, "language": "en" }
Responses:
- 200
The transcription result in the standard AIVAX JSON envelope.
{ "message": null, "data": { "message": null, "data": { "text": "Transcribed speech." } } } - 400
The model, audio data or format is invalid.
- 402
The account does not have a positive balance.
- 429
The request-level rate limit was exceeded.
Conversations
Get/api/v1/conversationsList Conversations
List Conversations
Lists recent conversations for observability, monitoring, and analysis. The list includes message previews, model, token usage, external user, error state, and usage resources.
GET /api/v1/conversationsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- offsetminutesinteger
Lookback window in minutes when timeStart is omitted. Defaults to 120 and is limited by the account conversation retention period.
- timeStartstring
Inclusive ISO 8601 start date, limited by the account conversation retention period.
- timeEndstring
Inclusive ISO 8601 end date. Defaults to the current time and must not precede timeStart.
- filterstring
Optional command-line style filters. Supported filters: --model|-m, --user|-u, --api-key, --gateway, --chat-client, and --chat-session.
Responses:
- 200
Recent conversations matching the requested filters.
{ "message": null, "data": [ { "id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f", "origin": "OpenAICompatibleApi", "updatedAt": "2026-06-17T13:42:10.0000000-03:00", "tokenCount": 1842, "modelName": "openai/gpt-4.1-mini", "externalUserId": "customer-42", "isError": false, "messagesPreview": { "input": "Preciso de um resumo do pedido.", "output": "Claro. O pedido cont\u00E9m tr\u00EAs itens..." }, "resources": [ { "resourceType": "AiGateway", "resourceId": "2e8bde3e-f7f1-4a72-97fd-89bd755d377b" }, { "resourceType": "ChatClientSession", "resourceId": "498a50e0-6826-4f3d-a6b8-e11c79e226b2" } ] } ] }
Get/api/v1/conversations/<id>View Conversation
View Conversation
Returns full observability details for one stored conversation, including messages, request metadata, tools, response schema, usage object, resources, timestamps and error details.
GET /api/v1/conversations/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the conversation to retrieve.
Responses:
- 200
Conversation details.
{ "message": null, "data": { "id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f", "origin": "OpenAICompatibleApi", "modelName": "openai/gpt-4.1-mini", "requestId": "req_01jz8h7eqbe0hwx21b91m7m29v", "responseSchema": null, "tools": [ "search_documents" ], "toolInputSchemas": { "search_documents": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ] } }, "usageObject": { "prompt_tokens": 1120, "completion_tokens": 722, "total_tokens": 1842 }, "resources": [ { "resourceType": "AiGateway", "resourceId": "2e8bde3e-f7f1-4a72-97fd-89bd755d377b" } ], "timestamps": { "createdAt": "2026-06-17T13:41:38.0000000-03:00", "updatedAt": "2026-06-17T13:42:10.0000000-03:00" }, "tokenCount": 1842, "externalUserId": "customer-42", "errorMessage": null, "messages": [ { "role": "user", "content": "Preciso de um resumo do pedido." }, { "role": "assistant", "content": "Claro. O pedido cont\u00E9m tr\u00EAs itens..." } ], "metadata": { "channel": "whatsapp" } } } - 404
The conversation was not found.
- 403
The conversation does not belong to the authenticated account.
Delete/api/v1/conversations/<id>Delete Conversation
Delete Conversation
Deletes a stored conversation from the authenticated account.
DELETE /api/v1/conversations/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the conversation to delete.
Responses:
- 200
Conversation deleted successfully.
{ "message": null, "data": { "message": "Conversation deleted successfully." } } - 404
The conversation was not found.
- 403
The conversation does not belong to the authenticated account.
Get/api/v1/conversations/<id>/export.jsonExport Conversation (JSON)
Export Conversation (JSON)
Exports a single conversation as a JSON file using the same export options available for the JSONL export.
GET /api/v1/conversations/<id>/export.jsonHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- iduuid
Identifier of the conversation to export.
Query parameters:
- periodstring
Retention guard period. Accepted values: 2h, 1d, 7d, or 30d. Defaults to 7d.
- mediastring
Media export mode. Accepted values: text or include. Defaults to text.
- thinkingstring
Reasoning export mode. Accepted values: visible, all, or none. Defaults to visible.
- truncateinteger
Optional maximum token count for the exported conversation. Use 0 to disable truncation. Maximum value is 1,000,000.
Responses:
- 200
Conversation JSON file.
{ "message": null, "data": { "messages": [ { "role": "user", "content": "Preciso de um resumo do pedido." }, { "role": "assistant", "content": "Claro. O pedido cont\u00E9m tr\u00EAs itens..." } ], "model": "openai/gpt-4.1-mini", "conversation": { "id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f", "origin": "OpenAICompatibleApi", "externalUserId": "customer-42", "tokenCount": 1842, "createdAt": "2026-06-17T13:41:38.0000000-03:00", "updatedAt": "2026-06-17T13:42:10.0000000-03:00" } } } - 400
Invalid period, media, thinking, or truncate option.
- 404
The conversation was not found.
- 403
The conversation does not belong to the authenticated account.
Get/api/v1/conversations/management/export.jsonlExport Conversations (JSONL)
Export Conversations (JSONL)
Exports conversations from the authenticated account as JSONL for offline analysis, audits, and monitoring workflows.
GET /api/v1/conversations/management/export.jsonlHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- periodstring
Export period. Accepted values: 2h, 1d, 7d, or 30d. Defaults to 7d and is limited by the account retention period.
- mediastring
Media export mode. Accepted values: text or include. Defaults to text.
- thinkingstring
Reasoning export mode. Accepted values: visible, all, or none. Defaults to visible.
- truncateinteger
Optional maximum token count per exported conversation. Use 0 to disable truncation. Maximum value is 1,000,000.
Responses:
- 200
JSONL file stream. Each line is a conversation export object.
{ "message": null, "data": { "messages": [ { "role": "user", "content": "Preciso de um resumo do pedido." }, { "role": "assistant", "content": "Claro. O pedido cont\u00E9m tr\u00EAs itens..." } ], "model": "openai/gpt-4.1-mini", "conversation": { "id": "9c3ab2d3-8726-4f6e-8fb1-7d69362e5b3f", "origin": "OpenAICompatibleApi", "externalUserId": "customer-42", "tokenCount": 1842 } } } - 400
Invalid period, media, thinking, or truncate option.
Collections
Get/api/v1/collectionsList Collections
List Collections
Lists RAG collections owned by the authenticated account with document counts by indexing state.
GET /api/v1/collectionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "name": string, "documentCount": { "queuedDocuments": number, "indexedDocuments": number, "outdatedDocuments": number, "totalDocuments": number } }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "name": { "type": "string" }, "documentCount": { "type": "object", "properties": { "queuedDocuments": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "indexedDocuments": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "outdatedDocuments": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalDocuments": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } } } } }
Post/api/v1/collectionsCreate Collection
Create Collection
Creates an empty RAG collection that can receive documents and later be searched or attached to an AI Gateway.
POST /api/v1/collectionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
Collection creation payload.
{ "collectionName": string, "context": string?, "tags": string? }{ "type": "object", "properties": { "collectionName": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "tags": { "type": [ "string", "null" ] } } }
Responses:
- 200
{ "message": null, "data": { "collectionId": "uuid" } }{ "type": "object", "properties": { "collectionId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } } }
Put/api/v1/collections/<collection-id>Edit Collection
Edit Collection
Updates a collection. The request may contain only the fields to change; omitted fields keep their current values. Send null for optional fields such as context or tags to clear them.
PUT /api/v1/collections/<collection-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to update.
Request examples:
Partial collection update data. The schema type documents the available fields, but update payloads may send only collectionName, context and/or tags.
{ "collectionName": string, "context": string?, "tags": string? }{ "type": "object", "additionalProperties": false, "properties": { "collectionName": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "tags": { "type": [ "string", "null" ] } } }
Responses:
- 200
The collection was saved.
Get/api/v1/collections/<collection-id>Get Collection Details
Get Collection Details
Returns a collection's name, creation time, indexing state, discovered tags, contextual tags and RAG usage statistics.
GET /api/v1/collections/<collection-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to inspect.
Responses:
- 200
Collection metadata, indexing state and usage statistics.
{ "message": null, "data": { "name": "My Collection", "createdAt": "2023-10-27T10:00:00Z", "state": { "total": 100, "indexed": 90, "queued": 10 }, "tags": [ "tag1", "tag2" ] } }
Delete/api/v1/collections/<collection-id>Delete Collection
Delete Collection
Deletes the collection and its stored documents for the authenticated account.
DELETE /api/v1/collections/<collection-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to delete.
Responses:
- 200
The collection was deleted.
Delete/api/v1/collections/<collection-id>/reset-onlyReset Collection
Reset Collection
Deletes all documents from a collection while keeping the collection record and configuration.
DELETE /api/v1/collections/<collection-id>/reset-onlyHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to empty.
Responses:
- 200
All documents were removed from the collection.
Delete/api/v1/collections/<collection-id>/vectors-onlyUpdate Collection Vectors
Update Collection Vectors
Marks every document vector in the collection as outdated so the indexing job rebuilds embeddings.
DELETE /api/v1/collections/<collection-id>/vectors-onlyHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection whose vectors should be rebuilt.
Responses:
- 200
Documents with outdated vectors were queued for re-indexing.
Get/api/v1/collections/<collection-id>/transactionsList Collection RAG Transactions
List Collection RAG Transactions
Lists recent, low-quality, or high-quality RAG transactions for one collection within the account plan retention period.
GET /api/v1/collections/<collection-id>/transactionsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to inspect.
Query parameters:
- viewstring
View mode. Accepted values: recent, low-quality, or high-quality.
Responses:
- 200
{ "message": null, "data": [ { "id": number, // UUID/GUID string "requestId": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "originalScore": number?, "rerankerScore": number?, "finalScore": number?, "rerankerName": string?, "queryTerm": string, "results": number, "processTimeMs": number }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "requestId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "originalScore": { "type": [ "number", "null" ] }, "rerankerScore": { "type": [ "number", "null" ] }, "finalScore": { "type": [ "number", "null" ] }, "rerankerName": { "type": [ "string", "null" ] }, "queryTerm": { "type": "string" }, "results": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "processTimeMs": { "type": "integer", "minimum": -9223372036854780000, "maximum": 9223372036854780000 } } } }
Get/api/v1/collections/<collection-id>/export.jsonlExport Collection
Export Collection
Streams all documents in the collection as JSONL lines containing docid, text, reference and tags.
GET /api/v1/collections/<collection-id>/export.jsonlHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to export.
Responses:
- 200
JSONL file stream containing one document per line.
Post/api/v1/collections/<collection-id>/deduplicationStart Collection De-duplication
Start Collection De-duplication
Starts an asynchronous collection de-duplication task. Deleted documents are periodically archived as JSONL files in Backblaze B2 before removal. Completion is reported by app and e-mail notification with backup download links.
POST /api/v1/collections/<collection-id>/deduplicationHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to de-duplicate.
Query parameters:
- deltastring
Duplication sensitivity. Accepted values: low, medium or high. Defaults to medium.
Responses:
- 202
The de-duplication task was accepted and will run after the response is sent.
Get/api/v1/collections/<collection-id>/deduplication/estimateEstimate Collection De-duplication
Estimate Collection De-duplication
Estimates processing-unit consumption and cost for asynchronously removing exact and semantic duplicate documents from a collection.
GET /api/v1/collections/<collection-id>/deduplication/estimateHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to de-duplicate.
Query parameters:
- deltastring
Duplication sensitivity. Accepted values: low, medium or high. Defaults to medium.
Responses:
- 200
Estimated document count, processing units, cost and per-unit price.
Get/api/v1/collections/<collection-id>/transactions/export/jsonlExport Collection RAG Transactions
Export Collection RAG Transactions
Streams the selected RAG transaction view as JSONL.
GET /api/v1/collections/<collection-id>/transactions/export/jsonlHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection to inspect.
Query parameters:
- viewstring
View mode. Accepted values: recent, low-quality, or high-quality.
Responses:
- 200
JSONL file stream containing one RAG transaction per line.
Get/api/v1/collections/<collection-id>/transactions/<transaction-id>View Collection RAG Transaction
View Collection RAG Transaction
Returns one RAG transaction with cost, timing, scores, reranker metadata, and matched documents.
GET /api/v1/collections/<collection-id>/transactions/<transaction-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection that owns the transaction.
- transaction-idinteger
Identifier of the RAG transaction.
Responses:
- 200
{ "message": null, "data": { "id": number, // UUID/GUID string "requestId": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "queryTerm": string, "processTimeMs": number, "cost": number, "originalScore": number?, "rerankerScore": number?, "finalScore": number?, "rerankerName": string?, "results": [ { // UUID/GUID string "documentId": "uuid", "documentName": string?, "contentsPreview": string?, "originalScore": number?, "rerankerScore": number?, "score": number }, ... ] } }{ "type": "object", "properties": { "id": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "requestId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "queryTerm": { "type": "string" }, "processTimeMs": { "type": "integer", "minimum": -9223372036854780000, "maximum": 9223372036854780000 }, "cost": { "type": "number" }, "originalScore": { "type": [ "number", "null" ] }, "rerankerScore": { "type": [ "number", "null" ] }, "finalScore": { "type": [ "number", "null" ] }, "rerankerName": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "documentName": { "type": [ "string", "null" ] }, "contentsPreview": { "type": [ "string", "null" ] }, "originalScore": { "type": [ "number", "null" ] }, "rerankerScore": { "type": [ "number", "null" ] }, "score": { "type": "number" } } } } } }
Documents
Get/api/v1/collections/<collection-id>/documentsBrowse Documents
Browse Documents
Lists up to 200 documents from a collection without a text filter, or up to 300 documents when a text filter is provided.
GET /api/v1/collections/<collection-id>/documentsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection that contains the documents.
Query parameters:
- filterstring
Plain text search across name, reference, contents and tags, or command syntax such as -t tag -n name -r reference -c content -i id.
- order_bystring
Sort order: created_at_asce, created_at_desc, updated_at_asce, updated_at_desc, indexed_at_asce or indexed_at_desc.
- statestring
Indexing state filter. Accepted values: queued or indexed.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "updatedAt": "date-time", "name": string, "reference": string?, "tags": [ string, ... ], "contentsPreview": string, "indexState": "Queued" }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "name": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "contentsPreview": { "type": "string" }, "indexState": { "type": "string", "enum": [ "Queued", "Cancelled", "Indexed" ] } } } }
Post/api/v1/collections/<collection-id>/documentsIndex Documents (JSONL)
Index Documents (JSONL)
Uploads documents from a JSONL file. Existing documents are matched by docId: changed text queues reindexing; changed text with non-null __meta also updates metadata; changed text with null or omitted __meta keeps current metadata; changed __meta alone updates metadata without reindexing; new docIds are created. When insert-mode is sync, documents missing from the uploaded JSONL are deleted.
POST /api/v1/collections/<collection-id>/documentsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection that will receive the documents.
Request parameters:
- documentsfile
JSONL file containing one document object per line.
Examples:
JSONL document file
File contents with one document JSON object per line.
{"docId":"getting-started","text":"Open the dashboard and create your first collection.","__ref":"https://example.com/docs/getting-started","__tags":["guide","onboarding"],"__meta":{"language":"en"}} {"docId":"pricing","text":"Plans are billed monthly and can be changed at any time.","__tags":["billing"]} - insert-modestring
Set to sync to delete collection documents whose names are not present in the uploaded JSONL file.
Request examples:
Multipart form data with a documents file. Each JSONL line must contain docId and text, and may contain __ref, __tags and __meta.
{"docId":"getting-started","text":"Open the dashboard and create your first collection.","__ref":"https://example.com/docs/getting-started","__tags":["guide","onboarding"],"__meta":{"language":"en"}} {"docId":"pricing","text":"Plans are billed monthly and can be changed at any time.","__tags":["billing"]}
Responses:
- 200
{ "message": null, "data": { "enqueued": number, "skipped": number } }{ "type": "object", "properties": { "enqueued": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "skipped": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }
Put/api/v1/collections/<collection-id>/documentsCreate or Update Document
Create or Update Document
Creates or updates a single document matched by name. name is required to identify the document. Existing documents may be updated with a partial payload: omitted contents, reference, tags and metadata keep their current values. Changed contents queue reindexing; metadata objects are shallow-merged with current metadata without reindexing when contents are unchanged; null or omitted metadata keeps current metadata. Missing documents are created and require contents.
PUT /api/v1/collections/<collection-id>/documentsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection that contains or will receive the document.
Request examples:
Document data. The schema type documents the available fields. For existing documents, send name and only the fields to change.
{ "contents": string, "name": string, "reference": string?, "tags": [ string, ... ]?, "metadata": {}? }{ "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" }, "contents": { "type": "string", "description": "Required when creating a missing document. Optional for existing documents." }, "reference": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "metadata": { "type": [ "object", "null" ], "description": "Partial metadata object. When supplied for an existing document, it is shallow-merged with current metadata." } } }
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "documentId": "uuid", "state": string } }{ "type": "object", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "state": { "type": "string" } } }
Post/api/v1/collections/<collection-id>/documents/media/chunkUpload Media Document Chunk
Upload Media Document Chunk
Appends a binary media file chunk to an in-progress document import.
POST /api/v1/collections/<collection-id>/documents/media/chunkHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Import-Media-File-NameRequired
Original media file name. Required for the import.
- X-Import-Media-File-Name-Encoding
Set to percent when X-Import-Media-File-Name is percent-encoded.
- X-Import-Media-Upload-IdRequired
UUID that identifies this upload and must also be sent when completing it.
Path parameters:
- collection-iduuid
Identifier of the collection that will receive the imported document.
Request examples:
Binary media file chunk.
Responses:
- 200
The chunk was appended to the pending upload.
- 400
The upload headers or binary request body are missing or invalid.
Get/api/v1/collections/<collection-id>/documents/<document-id>Get Document
Get Document
Returns the full stored document, including contents, metadata, tags, timestamps and indexing state.
GET /api/v1/collections/<collection-id>/documents/<document-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection that contains the document.
- document-iduuid
Identifier of the document to retrieve.
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "id": "uuid", "name": string, "state": "Queued", "contents": string, "reference": string?, "tags": [ string, ... ], // ISO 8601 date-time string "createdAt": "date-time", // ISO 8601 date-time string "updatedAt": "date-time", // Nullable. ISO 8601 date-time string "indexedAt": "date-time"?, "characterCount": number, "wordCount": number, "approximateTokenCount": number, "metadata": {} } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "state": { "type": "string", "enum": [ "Queued", "Cancelled", "Indexed" ] }, "contents": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "indexedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "characterCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "wordCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "approximateTokenCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "metadata": { "type": "object" } } }
Delete/api/v1/collections/<collection-id>/documents/<document-id>Delete Document
Delete Document
Deletes one document from a collection. When include-references is present, deletes documents in the same collection that share the selected document's reference.
DELETE /api/v1/collections/<collection-id>/documents/<document-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- collection-iduuid
Identifier of the collection that contains the document.
- document-iduuid
Identifier of the document to delete.
Responses:
- 200
The document was removed.
- 403
The collection does not belong to the authenticated account.
Post/api/v1/collections/<collection-id>/documents/media/completeComplete Media Document Import
Complete Media Document Import
Queues processing of the binary media upload previously sent in chunks.
POST /api/v1/collections/<collection-id>/documents/media/completeHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key). - X-Import-Media-File-NameRequired
Original media file name used for the completed import.
- X-Import-Media-File-Name-Encoding
Set to percent when X-Import-Media-File-Name is percent-encoded.
- X-Import-Media-Upload-IdRequired
UUID that identifies the chunks to process.
Path parameters:
- collection-iduuid
Identifier of the collection that will receive the imported document.
Request parameters:
- $.contextstring
Optional context used while processing the imported media.
Request examples:
Media import completion payload.
{ "context": "Product catalog for the sales assistant" }
Responses:
- 200
The media import was accepted for asynchronous processing.
- 400
The completion payload or upload headers are missing or invalid.
- 429
The media processing upload rate limit was exceeded.
Batch
Get/api/v1/batch/jobsList Account Batch Jobs
List Account Batch Jobs
Lists recent batch jobs across all workflows owned by the authenticated account.
GET /api/v1/batch/jobsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- filterstring
Optional search over job id or title.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // UUID/GUID string "parentBatchWorkflowId": "uuid", "workflowTitle": string?, "title": string?, // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "pending": number, "finished": number, "refused": number, "executionErrors": number, "validationErrors": number, "cancelled": number, "running": number, "totalCost": number, "averageConfidence": number?, "successRate": number, "refusalRate": number, "eventCount": number, "failed": number, "completed": number, "total": number }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "workflowTitle": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "pending": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "refused": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "executionErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "validationErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cancelled": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "running": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalCost": { "type": "number" }, "averageConfidence": { "type": [ "number", "null" ] }, "successRate": { "type": "number" }, "refusalRate": { "type": "number" }, "eventCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "total": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } } }
Get/api/v1/batch/workflowsList Batch Workflows
List Batch Workflows
Lists batch workflows owned by the authenticated account, including model, validation status and job count.
GET /api/v1/batch/workflowsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- filterstring
Optional search over workflow id, title, model name or instruction text.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", // ISO 8601 date-time string "updatedAt": "date-time", "title": string?, "modelName": string, "validationEnabled": boolean, "jobCount": number }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "title": { "type": [ "string", "null" ] }, "modelName": { "type": "string" }, "validationEnabled": { "type": "boolean" }, "jobCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } } }
Post/api/v1/batch/workflowsCreate Batch Workflow
Create Batch Workflow
Creates a reusable batch workflow that defines item instructions, result schema, model, validation and retry behavior.
POST /api/v1/batch/workflowsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
Workflow creation JSON object. Required fields are instruction, resultSchema and modelName; title and validation settings are optional.
Responses:
- 200
{ "message": null, "data": { "id": "uuid" } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } } }
Get/api/v1/batch/workflows/<workflow-id>View Batch Workflow
View Batch Workflow
Returns a batch workflow's title, timestamps and full processing options.
GET /api/v1/batch/workflows/<workflow-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the workflow to retrieve.
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", // ISO 8601 date-time string "updatedAt": "date-time", "title": string?, "options": { "instruction": string, "resultSchema": any, "validationInstruction": string?, "enabledTools": { "enabledFunctions": [ "WebSearch", ... ], "options": { "webSearchMode": "Full", "webSearchMaxResults": number, "imageGenerationMaxResults": number, "imageGenerationQuality": "Low", "imageGenerationAllowMatureContent": boolean, "imageGenerationAllowReferenceUsage": boolean, "imageGenerationModelName": string?, "includeAllMemoryContext": boolean, "allowSharedMemory": boolean } }, "modelName": string, "reasoningEffort": string?, "errorStopThreshold": number, "maxRetries": number } } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "title": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "instruction": { "type": "string" }, "resultSchema": {}, "validationInstruction": { "type": [ "string", "null" ] }, "enabledTools": { "type": "object", "properties": { "enabledFunctions": { "type": "array", "items": { "type": "string", "enum": [ "WebSearch", "Code", "OpenUrl", "Remember", "ImageGeneration", "XPostsSearch", "GenerateDocument", "GenerateWebPage", "AdvancedWebUsage", "Request", "Calendar" ] } }, "options": { "type": "object", "properties": { "webSearchMode": { "type": "string", "enum": [ "Full", "Summarized" ] }, "webSearchMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationQuality": { "type": "string", "enum": [ "Low", "Medium", "High", "Highest" ] }, "imageGenerationAllowMatureContent": { "type": "boolean" }, "imageGenerationAllowReferenceUsage": { "type": "boolean" }, "imageGenerationModelName": { "type": [ "string", "null" ] }, "includeAllMemoryContext": { "type": "boolean" }, "allowSharedMemory": { "type": "boolean" } } } } }, "modelName": { "type": "string" }, "reasoningEffort": { "type": [ "string", "null" ] }, "errorStopThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "maxRetries": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "instruction", "resultSchema", "modelName" ] } } }
Patch/api/v1/batch/workflows/<workflow-id>Edit Batch Workflow
Edit Batch Workflow
Edits a batch workflow. The request may contain only the fields to change; omitted fields keep their current values. enabledTools is shallow-merged with the existing object when provided, replacing only supplied top-level keys.
PATCH /api/v1/batch/workflows/<workflow-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the workflow to update.
Request examples:
Partial workflow JSON object. Send title, instruction, resultSchema, validationInstruction, enabledTools, modelName, reasoningEffort, errorStopThreshold and/or maxRetries.
{ "type": "object", "additionalProperties": false, "properties": { "title": { "type": [ "string", "null" ] }, "instruction": { "type": "string" }, "resultSchema": { "type": "object", "description": "JSON schema object for workflow results." }, "validationInstruction": { "type": [ "string", "null" ] }, "enabledTools": { "type": "object", "description": "Partial enabled tools object. This is shallow-merged with current enabled tools." }, "modelName": { "type": "string" }, "reasoningEffort": { "type": [ "string", "null" ] }, "errorStopThreshold": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxRetries": { "type": "integer", "minimum": 0, "maximum": 10 } } }
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", // ISO 8601 date-time string "updatedAt": "date-time", "title": string?, "options": { "instruction": string, "resultSchema": any, "validationInstruction": string?, "enabledTools": { "enabledFunctions": [ "WebSearch", ... ], "options": { "webSearchMode": "Full", "webSearchMaxResults": number, "imageGenerationMaxResults": number, "imageGenerationQuality": "Low", "imageGenerationAllowMatureContent": boolean, "imageGenerationAllowReferenceUsage": boolean, "imageGenerationModelName": string?, "includeAllMemoryContext": boolean, "allowSharedMemory": boolean } }, "modelName": string, "reasoningEffort": string?, "errorStopThreshold": number, "maxRetries": number } } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "title": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "instruction": { "type": "string" }, "resultSchema": {}, "validationInstruction": { "type": [ "string", "null" ] }, "enabledTools": { "type": "object", "properties": { "enabledFunctions": { "type": "array", "items": { "type": "string", "enum": [ "WebSearch", "Code", "OpenUrl", "Remember", "ImageGeneration", "XPostsSearch", "GenerateDocument", "GenerateWebPage", "AdvancedWebUsage", "Request", "Calendar" ] } }, "options": { "type": "object", "properties": { "webSearchMode": { "type": "string", "enum": [ "Full", "Summarized" ] }, "webSearchMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationQuality": { "type": "string", "enum": [ "Low", "Medium", "High", "Highest" ] }, "imageGenerationAllowMatureContent": { "type": "boolean" }, "imageGenerationAllowReferenceUsage": { "type": "boolean" }, "imageGenerationModelName": { "type": [ "string", "null" ] }, "includeAllMemoryContext": { "type": "boolean" }, "allowSharedMemory": { "type": "boolean" } } } } }, "modelName": { "type": "string" }, "reasoningEffort": { "type": [ "string", "null" ] }, "errorStopThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "maxRetries": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "instruction", "resultSchema", "modelName" ] } } }
Delete/api/v1/batch/workflows/<workflow-id>Delete Batch Workflow
Delete Batch Workflow
Deletes a batch workflow and all jobs and items created under it.
DELETE /api/v1/batch/workflows/<workflow-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the workflow to delete.
Responses:
- 200
The batch workflow and its jobs were deleted.
Get/api/v1/batch/workflows/<workflow-id>/jobsList Batch Jobs
List Batch Jobs
Lists jobs under a batch workflow with aggregated processing summary.
GET /api/v1/batch/workflows/<workflow-id>/jobsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
Query parameters:
- filterstring
Optional search over job id or title.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // UUID/GUID string "parentBatchWorkflowId": "uuid", "workflowTitle": string?, "title": string?, // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "pending": number, "finished": number, "refused": number, "executionErrors": number, "validationErrors": number, "cancelled": number, "running": number, "totalCost": number, "averageConfidence": number?, "successRate": number, "refusalRate": number, "eventCount": number, "failed": number, "completed": number, "total": number }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "workflowTitle": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "pending": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "refused": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "executionErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "validationErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cancelled": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "running": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalCost": { "type": "number" }, "averageConfidence": { "type": [ "number", "null" ] }, "successRate": { "type": "number" }, "refusalRate": { "type": "number" }, "eventCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "total": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } } }
Post/api/v1/batch/workflows/<workflow-id>/jobsCreate Batch Job
Create Batch Job
Creates a paused job under a batch workflow. Import items, then start the job through the edit endpoint.
POST /api/v1/batch/workflows/<workflow-id>/jobsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
Request examples:
Optional JSON object with a title field.
Responses:
- 200
{ "message": null, "data": { "id": "uuid" } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } } }
Get/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>View Batch Job
View Batch Job
Returns a batch job, aggregated summary, progression timeline and latest processed items.
GET /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job to retrieve.
Responses:
- 200
{ "message": null, "data": { "job": { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "title": string?, // Required. UUID/GUID string "parentBatchWorkflowId": "uuid", "updates": [ { // ISO 8601 date-time string "moment": "date-time", "eventType": string, "description": string }, ... ] }, "summary": { // UUID/GUID string "id": "uuid", // UUID/GUID string "parentBatchWorkflowId": "uuid", "workflowTitle": string?, "title": string?, // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "pending": number, "finished": number, "refused": number, "executionErrors": number, "validationErrors": number, "cancelled": number, "running": number, "totalCost": number, "averageConfidence": number?, "successRate": number, "refusalRate": number, "eventCount": number, "failed": number, "completed": number, "total": number }, "progression": [ { // ISO 8601 date-time string "moment": "date-time", "finished": number, "failed": number, "averageConfidence": number?, "refusalRate": number }, ... ], "latestItems": [ { // UUID/GUID string "id": "uuid", // Required. UUID/GUID string "parentBatchWorkflowJobId": "uuid", // ISO 8601 date-time string "insertedAt": "date-time", // Nullable. ISO 8601 date-time string "processedAt": "date-time"?, "state": "Pending", "priority": number, "input": string, "output": string?, "validationResult": { "passed": boolean, "reason": string? }?, "confidence": number?, "totalCost": number? }, ... ] } }{ "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "moment": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "eventType": { "type": "string" }, "description": { "type": "string" } }, "required": [ "eventType", "description" ] } } }, "required": [ "parentBatchWorkflowId" ] }, "summary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "workflowTitle": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "pending": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "refused": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "executionErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "validationErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cancelled": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "running": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalCost": { "type": "number" }, "averageConfidence": { "type": [ "number", "null" ] }, "successRate": { "type": "number" }, "refusalRate": { "type": "number" }, "eventCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "total": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "progression": { "type": "array", "items": { "type": "object", "properties": { "moment": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "averageConfidence": { "type": [ "number", "null" ] }, "refusalRate": { "type": "number" } } } }, "latestItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowJobId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "insertedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "processedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "Pending", "Finished", "Refused", "ExecutionError", "ValidationError", "Cancelled" ] }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "validationResult": { "properties": { "passed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "totalCost": { "type": [ "number", "null" ] } }, "required": [ "parentBatchWorkflowJobId", "input" ] } } } }
Patch/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>Edit Batch Job
Edit Batch Job
Changes a job title or state. Setting state to Active starts processing; Paused or Finished stops further processing.
PATCH /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job to update.
Request examples:
Partial job update JSON object. Send title and/or state.
Responses:
- 200
{ "message": null, "data": { "job": { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "title": string?, // Required. UUID/GUID string "parentBatchWorkflowId": "uuid", "updates": [ { // ISO 8601 date-time string "moment": "date-time", "eventType": string, "description": string }, ... ] }, "summary": { // UUID/GUID string "id": "uuid", // UUID/GUID string "parentBatchWorkflowId": "uuid", "workflowTitle": string?, "title": string?, // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "pending": number, "finished": number, "refused": number, "executionErrors": number, "validationErrors": number, "cancelled": number, "running": number, "totalCost": number, "averageConfidence": number?, "successRate": number, "refusalRate": number, "eventCount": number, "failed": number, "completed": number, "total": number }, "progression": [ { // ISO 8601 date-time string "moment": "date-time", "finished": number, "failed": number, "averageConfidence": number?, "refusalRate": number }, ... ], "latestItems": [ { // UUID/GUID string "id": "uuid", // Required. UUID/GUID string "parentBatchWorkflowJobId": "uuid", // ISO 8601 date-time string "insertedAt": "date-time", // Nullable. ISO 8601 date-time string "processedAt": "date-time"?, "state": "Pending", "priority": number, "input": string, "output": string?, "validationResult": { "passed": boolean, "reason": string? }?, "confidence": number?, "totalCost": number? }, ... ] } }{ "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "moment": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "eventType": { "type": "string" }, "description": { "type": "string" } }, "required": [ "eventType", "description" ] } } }, "required": [ "parentBatchWorkflowId" ] }, "summary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "workflowTitle": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "pending": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "refused": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "executionErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "validationErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cancelled": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "running": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalCost": { "type": "number" }, "averageConfidence": { "type": [ "number", "null" ] }, "successRate": { "type": "number" }, "refusalRate": { "type": "number" }, "eventCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "total": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "progression": { "type": "array", "items": { "type": "object", "properties": { "moment": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "averageConfidence": { "type": [ "number", "null" ] }, "refusalRate": { "type": "number" } } } }, "latestItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowJobId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "insertedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "processedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "Pending", "Finished", "Refused", "ExecutionError", "ValidationError", "Cancelled" ] }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "validationResult": { "properties": { "passed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "totalCost": { "type": [ "number", "null" ] } }, "required": [ "parentBatchWorkflowJobId", "input" ] } } } }
Delete/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>Delete Batch Job
Delete Batch Job
Deletes a batch job and every item under it.
DELETE /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job to delete.
Responses:
- 200
The batch job and its items were deleted.
Post/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/itemsImport Batch Job Items
Import Batch Job Items
Imports batch job items from multipart/form-data. Mode 'lines' imports each non-empty file line; mode 'files' imports each uploaded text file as one item; mode 'zip' imports each text file entry as one item; mode 'text' imports the submitted text field as one item.
POST /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/itemsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job that will receive items.
Request parameters:
- modestring
Import mode: lines, files, zip, or text. Defaults to lines when omitted.
- itemsfile
The uploaded file or files. In lines mode, each non-empty line is imported. In files mode, each file is imported as one item. In zip mode, each text entry is imported as one item.
- documentsfile
Accepted alias for the items file field.
- textstring
Manual item input for text mode.
Request examples:
Multipart form data with a mode field: lines, files, zip, or text. The 'items' field contains uploaded files, 'documents' is accepted as a file alias, and 'text' contains manual item text for text mode.
{"name":"Customer A","email":"[email protected]"} {"name":"Customer B","email":"[email protected]"}
Responses:
- 200
{ "message": null, "data": { "inserted": number, "skipped": number } }{ "type": "object", "properties": { "inserted": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "skipped": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }
Get/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/itemsList Batch Job Items
List Batch Job Items
Lists batch job items with optional state, confidence and text filters and configurable ordering. Results are capped to protect large jobs.
GET /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/itemsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job whose items will be listed.
Query parameters:
- statestring
Optional item state filter, such as Pending, Finished, ExecutionError or ValidationError.
- confidencestring
Optional confidence filter. Accepted values: high, high-confidence, low or low-confidence.
- filterstring
Optional text search over item input.
- sortstring
Item ordering. Accepted values: inserted-desc, inserted-asc, processed-desc or processed-asc. Defaults to inserted-desc.
- limitinteger
Maximum number of items to return. The endpoint enforces an upper bound.
Responses:
- 200
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "insertedAt": "date-time", "state": "Pending", "isRunning": boolean, "priority": number, "input": string, "confidence": number?, "totalCost": number? }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "insertedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Pending", "Finished", "Refused", "ExecutionError", "ValidationError", "Cancelled" ] }, "isRunning": { "type": "boolean" }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "input": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "totalCost": { "type": [ "number", "null" ] } } } }
Delete/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/itemsRemove Batch Job Items
Remove Batch Job Items
Bulk-deletes non-running items from a job by mode: pending, finished, errors or all.
DELETE /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/itemsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job whose items will be removed.
Query parameters:
- modestring
Deletion mode. Accepted values: pending, finished, errors or all.
Responses:
- 200
Matching items were removed.
Post/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/retryRetry Batch Job Items
Retry Batch Job Items
Moves selected failed or low-confidence non-running items back to pending and starts the job when at least one item is retried.
POST /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/retryHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job whose items will be retried.
Query parameters:
- modestring
Retry mode. Accepted values: errors, execution-error, validation-error or low-confidence.
Responses:
- 200
{ "message": null, "data": { "job": { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "title": string?, // Required. UUID/GUID string "parentBatchWorkflowId": "uuid", "updates": [ { // ISO 8601 date-time string "moment": "date-time", "eventType": string, "description": string }, ... ] }, "summary": { // UUID/GUID string "id": "uuid", // UUID/GUID string "parentBatchWorkflowId": "uuid", "workflowTitle": string?, "title": string?, // ISO 8601 date-time string "createdAt": "date-time", "state": "Active", // Nullable. ISO 8601 date-time string "restartedAt": "date-time"?, "pending": number, "finished": number, "refused": number, "executionErrors": number, "validationErrors": number, "cancelled": number, "running": number, "totalCost": number, "averageConfidence": number?, "successRate": number, "refusalRate": number, "eventCount": number, "failed": number, "completed": number, "total": number }, "progression": [ { // ISO 8601 date-time string "moment": "date-time", "finished": number, "failed": number, "averageConfidence": number?, "refusalRate": number }, ... ], "latestItems": [ { // UUID/GUID string "id": "uuid", // Required. UUID/GUID string "parentBatchWorkflowJobId": "uuid", // ISO 8601 date-time string "insertedAt": "date-time", // Nullable. ISO 8601 date-time string "processedAt": "date-time"?, "state": "Pending", "priority": number, "input": string, "output": string?, "validationResult": { "passed": boolean, "reason": string? }?, "confidence": number?, "totalCost": number? }, ... ] } }{ "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "moment": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "eventType": { "type": "string" }, "description": { "type": "string" } }, "required": [ "eventType", "description" ] } } }, "required": [ "parentBatchWorkflowId" ] }, "summary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "workflowTitle": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "state": { "type": "string", "enum": [ "Active", "Paused", "Finished" ] }, "restartedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "pending": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "refused": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "executionErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "validationErrors": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "cancelled": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "running": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "totalCost": { "type": "number" }, "averageConfidence": { "type": [ "number", "null" ] }, "successRate": { "type": "number" }, "refusalRate": { "type": "number" }, "eventCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "completed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "total": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "progression": { "type": "array", "items": { "type": "object", "properties": { "moment": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "finished": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "failed": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "averageConfidence": { "type": [ "number", "null" ] }, "refusalRate": { "type": "number" } } } }, "latestItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowJobId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "insertedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "processedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "Pending", "Finished", "Refused", "ExecutionError", "ValidationError", "Cancelled" ] }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "validationResult": { "properties": { "passed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "totalCost": { "type": [ "number", "null" ] } }, "required": [ "parentBatchWorkflowJobId", "input" ] } } } }
Get/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/export.jsonlExport Batch Job
Export Batch Job
Streams processed batch job items as JSONL, including metadata, input and output. Pending items are not exported.
GET /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/export.jsonlHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the batch job to export.
Query parameters:
- statestring
Export state filter. Use all, finished, failed, errors, success or an item state name.
- confidencestring
Optional confidence filter. Accepted values: high, high-confidence, low or low-confidence.
Responses:
- 200
JSONL file stream containing one processed item per line.
Get/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/<item-id>View Batch Job Item
View Batch Job Item
Returns one batch item's input, output, state, validation result, confidence and cost.
GET /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/<item-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the parent batch job.
- item-iduuid
Identifier of the batch item to retrieve.
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "id": "uuid", // ISO 8601 date-time string "insertedAt": "date-time", // Nullable. ISO 8601 date-time string "processedAt": "date-time"?, "state": "Pending", "isRunning": boolean, "priority": number, "input": string, "output": string?, "validationResult": { "passed": boolean, "reason": string? }?, "confidence": number?, "totalCost": number? } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "insertedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "processedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "Pending", "Finished", "Refused", "ExecutionError", "ValidationError", "Cancelled" ] }, "isRunning": { "type": "boolean" }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "validationResult": { "properties": { "passed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "totalCost": { "type": [ "number", "null" ] } } }
Patch/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/<item-id>Edit Batch Job Item
Edit Batch Job Item
Changes a non-running batch item's priority or removes it when action is cancel.
PATCH /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/<item-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the parent batch job.
- item-iduuid
Identifier of the batch item to update.
Request examples:
Partial item update JSON object. Send priority to reprioritize, or action: cancel to remove the item.
Responses:
- 200
{ "message": null, "data": { // UUID/GUID string "id": "uuid", // Required. UUID/GUID string "parentBatchWorkflowJobId": "uuid", // ISO 8601 date-time string "insertedAt": "date-time", // Nullable. ISO 8601 date-time string "processedAt": "date-time"?, "state": "Pending", "priority": number, "input": string, "output": string?, "validationResult": { "passed": boolean, "reason": string? }?, "confidence": number?, "totalCost": number? } }{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "parentBatchWorkflowJobId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "insertedAt": { "type": "string", "format": "date-time", "description": "ISO 8601 date-time string" }, "processedAt": { "format": "date-time", "description": "ISO 8601 date-time string", "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "Pending", "Finished", "Refused", "ExecutionError", "ValidationError", "Cancelled" ] }, "priority": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "input": { "type": "string" }, "output": { "type": [ "string", "null" ] }, "validationResult": { "properties": { "passed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "totalCost": { "type": [ "number", "null" ] } }, "required": [ "parentBatchWorkflowJobId", "input" ] }
Delete/api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/<item-id>Delete Batch Job Item
Delete Batch Job Item
Deletes one non-running batch item from a job.
DELETE /api/v1/batch/workflows/<workflow-id>/jobs/<job-id>/items/<item-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- workflow-iduuid
Identifier of the parent workflow.
- job-iduuid
Identifier of the parent batch job.
- item-iduuid
Identifier of the batch item to delete.
Responses:
- 200
The item was removed.
Authentication
Post/api/v1/auth/loginLogin
Login
Authenticates an account using its login key and returns a 180-day access token along with basic account information. Rate limited to 10 attempts per minute per remote address.
POST /api/v1/auth/loginRequest examples:
Login payload containing the account login key delivered by email.
{ "loginKey": string }{ "type": "object", "properties": { "loginKey": { "type": "string" } } }
Responses:
- 200
Login succeeded and returned a 180-day account-management access token.
{ "message": null, "data": { "accessToken": string, "account": { // UUID/GUID string "id": "uuid", "name": string, "email": string, "emailSha256": string, "plan": "Free", "isAdmin": boolean, "parameters": { "allowConversationsLogging": boolean, "automaticJsonHealing": boolean, "allowSemanticDataCollection": boolean, "notifications": { "emails": [ string, ... ], "lowBalance": { "enabled": boolean, "threshold": number }, "deprecatedModels": { "enabled": boolean }, "weeklyTestingSummary": boolean, "repeatedTestFailures": boolean } } } } }{ "type": "object", "properties": { "accessToken": { "type": "string" }, "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "email": { "type": "string" }, "emailSha256": { "type": "string" }, "plan": { "type": "string", "enum": [ "Free", "Pro", "Max", "Reseller" ] }, "isAdmin": { "type": "boolean" }, "parameters": { "type": "object", "properties": { "allowConversationsLogging": { "type": "boolean" }, "automaticJsonHealing": { "type": "boolean" }, "allowSemanticDataCollection": { "type": "boolean" }, "notifications": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "lowBalance": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold": { "type": "number" } } }, "deprecatedModels": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "weeklyTestingSummary": { "type": "boolean" }, "repeatedTestFailures": { "type": "boolean" } } } } } } } } } - 400
Invalid or missing request body, invalid login key, or forbidden account.
- 429
Login rate limit exceeded for the current remote address.
AI Gateways
Post/api/v1/ai-gatewaysCreate AI Gateway
Create AI Gateway
Creates an AI Gateway runtime under the authenticated account. The gateway can combine model routing, instructions, RAG collections, built-in tools, protocol functions and MCP sources behind one inference endpoint.
POST /api/v1/ai-gatewaysHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
AI Gateway creation payload. Use parameters to configure model access, retrieval, tools, moderation and runtime behavior.
{ "name": string, "parameters": { "baseAddress": string, "transportInterface": "OpenAiCompatible", "routingOption": "Balanced", "skills": [ "uuid", ... ], "hideToolsWithoutSkill": boolean, "alwaysVisibleTools": [ string, ... ], "enableBash": boolean, "includeWorkspaceInstructions": boolean, "bashOptions": { "fileSystem": { "workingDirectory": string }?, "allowDataPersistence": boolean, "toolList": [ string, ... ], "toolExclusionMode": "WhiteList" }?, "knowledgeCollections": [ "uuid", ... ], "rerankerName": string?, "knowledgeBaseMaximumResults": number, "knowledgeBaseMinimumScore": number, "knowledgeUseReferences": boolean, "knowledgeUseMetaDescriptions": boolean, "queryStrategy": "Plain", "queryStrategyParameters": { "rewriteContextSize": number, "concatenateContextSize": number }, "apiKey": string?, "modelName": string, "temperature": number?, "topP": number?, "presencePenalty": number?, "frequencyPenalty": number?, "stop": string?, "maxCompletionTokens": number?, "contextMaximumSize": number?, "contextOverflowAction": "Throw", "systemInstruction": string?, "workerScriptSource": string?, "userPromptTemplate": string?, "assistantPrefill": string?, "includePrefillingInMessages": boolean, "reasoningEffort": string?, "verbosity": string?, "flags": [ "NoSystemInstruct", ... ], "tools": [ ... ]?, "protocolFunctions": [ { "name": string, "description": string, "headers": {}, "callbackUrl": string, "contentFormat": any }, ... ], "protocolFunctionSources": [ string, ... ], "mcpSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "systemInstructionsSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "enabledMultimodalFeatures": [ "Image", ... ], "toolContextCount": number?, "sentinelOptions": { "enabledFunctions": [ "WebSearch", ... ] }?, "builtinFunctionsOptions": { "webSearchMode": "Full", "webSearchMaxResults": number, "imageGenerationMaxResults": number, "imageGenerationQuality": "Low", "imageGenerationAllowMatureContent": boolean, "imageGenerationAllowReferenceUsage": boolean, "imageGenerationModelName": string?, "includeAllMemoryContext": boolean, "allowSharedMemory": boolean }?, "moderationParameters": { "violenceThreshold": number, "sexualExplicitThreshold": number, "politicalThreshold": number, "dangerousContentThreshold": number, "jailbreakThreshold": number, "offTopicThreshold": number, "additionalRules": string? }?, "knownToolHandlerName": string?, "toolInvocationExplanations": boolean, "modelRoutingParameters": { "lowComplexityModelName": string, "lowComplexityModelReasoningEffort": string?, "mediumComplexityModelName": string, "mediumComplexityModelReasoningEffort": string?, "highComplexityModelName": string, "highComplexityModelReasoningEffort": string? }?, "additionalSettings": {}? } }{ "type": "object", "properties": { "name": { "type": "string" }, "parameters": { "type": "object", "properties": { "baseAddress": { "type": "string" }, "transportInterface": { "type": "string", "enum": [ "OpenAiCompatible", "OpenAiChatCompletions", "OpenAiResponses" ] }, "routingOption": { "type": "string", "enum": [ "Balanced", "Cheapest", "Fastest", "Quality" ] }, "skills": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } }, "hideToolsWithoutSkill": { "type": "boolean" }, "alwaysVisibleTools": { "type": "array", "items": { "type": "string" } }, "enableBash": { "type": "boolean" }, "includeWorkspaceInstructions": { "type": "boolean" }, "bashOptions": { "properties": { "fileSystem": { "properties": { "workingDirectory": { "type": "string" } }, "type": [ "object", "null" ] }, "allowDataPersistence": { "type": "boolean" }, "toolList": { "type": "array", "items": { "type": "string" } }, "toolExclusionMode": { "type": "string", "enum": [ "WhiteList", "BlackList" ] } }, "type": [ "object", "null" ] }, "knowledgeCollections": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } }, "rerankerName": { "type": [ "string", "null" ] }, "knowledgeBaseMaximumResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "knowledgeBaseMinimumScore": { "type": "number" }, "knowledgeUseReferences": { "type": "boolean" }, "knowledgeUseMetaDescriptions": { "type": "boolean" }, "queryStrategy": { "type": "string", "enum": [ "Plain", "Concatenate", "FullRewrite", "UserRewrite", "QueryFunction" ] }, "queryStrategyParameters": { "type": "object", "properties": { "rewriteContextSize": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "concatenateContextSize": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "apiKey": { "type": [ "string", "null" ] }, "modelName": { "type": "string" }, "temperature": { "type": [ "number", "null" ] }, "topP": { "type": [ "number", "null" ] }, "presencePenalty": { "type": [ "number", "null" ] }, "frequencyPenalty": { "type": [ "number", "null" ] }, "stop": { "type": [ "string", "null" ] }, "maxCompletionTokens": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "contextMaximumSize": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "contextOverflowAction": { "type": "string", "enum": [ "Throw", "Truncate", "TruncateHard", "Compact" ] }, "systemInstruction": { "type": [ "string", "null" ] }, "workerScriptSource": { "type": [ "string", "null" ] }, "userPromptTemplate": { "type": [ "string", "null" ] }, "assistantPrefill": { "type": [ "string", "null" ] }, "includePrefillingInMessages": { "type": "boolean" }, "reasoningEffort": { "type": [ "string", "null" ] }, "verbosity": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "NoSystemInstruct", "NoTemperature", "ThinkingProcess", "NoAssistantPrefilling", "ReturnReasoningTokens", "DisableMultiModalInput", "DiffusingStream", "OpenAiStrictJson", "StructuredOutputSupport", "PreserveThinkingTokens", "NoStopParameter", "NoReasoningEffort", "RewriteToolCallsAsUserMessages", "DisableReasoningSummary", "DisableReasoningDetails", "IncludeStoredReasoning", "StrictUserAssistantTurns" ] } }, "tools": { "type": [ "array", "null" ] }, "protocolFunctions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "callbackUrl": { "type": "string" }, "contentFormat": {} }, "required": [ "name", "description", "callbackUrl", "contentFormat" ] } }, "protocolFunctionSources": { "type": "array", "items": { "type": "string" } }, "mcpSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "systemInstructionsSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "enabledMultimodalFeatures": { "type": "array", "items": { "type": "string", "enum": [ "Image", "Audio", "Video", "File", "OtherFiles", "All" ] } }, "toolContextCount": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "sentinelOptions": { "properties": { "enabledFunctions": { "type": "array", "items": { "type": "string", "enum": [ "WebSearch", "Code", "OpenUrl", "Remember", "ImageGeneration", "XPostsSearch", "GenerateDocument", "GenerateWebPage", "AdvancedWebUsage", "Request", "Calendar" ] } } }, "type": [ "object", "null" ] }, "builtinFunctionsOptions": { "properties": { "webSearchMode": { "type": "string", "enum": [ "Full", "Summarized" ] }, "webSearchMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationQuality": { "type": "string", "enum": [ "Low", "Medium", "High", "Highest" ] }, "imageGenerationAllowMatureContent": { "type": "boolean" }, "imageGenerationAllowReferenceUsage": { "type": "boolean" }, "imageGenerationModelName": { "type": [ "string", "null" ] }, "includeAllMemoryContext": { "type": "boolean" }, "allowSharedMemory": { "type": "boolean" } }, "type": [ "object", "null" ] }, "moderationParameters": { "properties": { "violenceThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "sexualExplicitThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "politicalThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "dangerousContentThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "jailbreakThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "offTopicThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "additionalRules": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "knownToolHandlerName": { "type": [ "string", "null" ] }, "toolInvocationExplanations": { "type": "boolean" }, "modelRoutingParameters": { "properties": { "lowComplexityModelName": { "type": "string" }, "lowComplexityModelReasoningEffort": { "type": [ "string", "null" ] }, "mediumComplexityModelName": { "type": "string" }, "mediumComplexityModelReasoningEffort": { "type": [ "string", "null" ] }, "highComplexityModelName": { "type": "string" }, "highComplexityModelReasoningEffort": { "type": [ "string", "null" ] } }, "required": [ "lowComplexityModelName", "mediumComplexityModelName", "highComplexityModelName" ], "type": [ "object", "null" ] }, "additionalSettings": { "type": [ "object", "null" ] } }, "required": [ "baseAddress", "modelName" ] } } }
Responses:
- 200
The gateway was created and the response contains its identifier.
{ "message": null, "data": { "aiGatewayId": "uuid" } }{ "type": "object", "properties": { "aiGatewayId": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } } }
Get/api/v1/ai-gatewaysList AI Gateways
List AI Gateways
Lists AI Gateways owned by the authenticated account with model, inference endpoint and slug summary fields.
GET /api/v1/ai-gatewaysHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Query parameters:
- filter
An optional filter string to search gateways by name, model name, slug, or ID.
Responses:
- 200
Gateway summaries for the authenticated account.
{ "message": null, "data": [ { // UUID/GUID string "id": "uuid", "name": string, "inferenceEndpoint": string?, "modelName": string, "slug": string }, ... ] }{ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID/GUID string" }, "name": { "type": "string" }, "inferenceEndpoint": { "type": [ "string", "null" ] }, "modelName": { "type": "string" }, "slug": { "type": "string" } } } }
Patch/api/v1/ai-gateways/<id>Edit AI Gateway
Edit AI Gateway
Edits an existing AI gateway. The request may contain only the fields to change; omitted fields keep their current values. When parameters is provided, it is shallow-merged with the existing gateway parameters and only supplied top-level parameter keys are replaced.
PATCH /api/v1/ai-gateways/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- id
Identifier of the AI Gateway to edit.
Request examples:
Partial or complete AI gateway modification payload. The schema type documents the available fields, but update payloads may send only name and/or a top-level subset of parameters.
{ "name": string, "parameters": { "baseAddress": string, "transportInterface": "OpenAiCompatible", "routingOption": "Balanced", "skills": [ "uuid", ... ], "hideToolsWithoutSkill": boolean, "alwaysVisibleTools": [ string, ... ], "enableBash": boolean, "includeWorkspaceInstructions": boolean, "bashOptions": { "fileSystem": { "workingDirectory": string }?, "allowDataPersistence": boolean, "toolList": [ string, ... ], "toolExclusionMode": "WhiteList" }?, "knowledgeCollections": [ "uuid", ... ], "rerankerName": string?, "knowledgeBaseMaximumResults": number, "knowledgeBaseMinimumScore": number, "knowledgeUseReferences": boolean, "knowledgeUseMetaDescriptions": boolean, "queryStrategy": "Plain", "queryStrategyParameters": { "rewriteContextSize": number, "concatenateContextSize": number }, "apiKey": string?, "modelName": string, "temperature": number?, "topP": number?, "presencePenalty": number?, "frequencyPenalty": number?, "stop": string?, "maxCompletionTokens": number?, "contextMaximumSize": number?, "contextOverflowAction": "Throw", "systemInstruction": string?, "workerScriptSource": string?, "userPromptTemplate": string?, "assistantPrefill": string?, "includePrefillingInMessages": boolean, "reasoningEffort": string?, "verbosity": string?, "flags": [ "NoSystemInstruct", ... ], "tools": [ ... ]?, "protocolFunctions": [ { "name": string, "description": string, "headers": {}, "callbackUrl": string, "contentFormat": any }, ... ], "protocolFunctionSources": [ string, ... ], "mcpSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "systemInstructionsSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "enabledMultimodalFeatures": [ "Image", ... ], "toolContextCount": number?, "sentinelOptions": { "enabledFunctions": [ "WebSearch", ... ] }?, "builtinFunctionsOptions": { "webSearchMode": "Full", "webSearchMaxResults": number, "imageGenerationMaxResults": number, "imageGenerationQuality": "Low", "imageGenerationAllowMatureContent": boolean, "imageGenerationAllowReferenceUsage": boolean, "imageGenerationModelName": string?, "includeAllMemoryContext": boolean, "allowSharedMemory": boolean }?, "moderationParameters": { "violenceThreshold": number, "sexualExplicitThreshold": number, "politicalThreshold": number, "dangerousContentThreshold": number, "jailbreakThreshold": number, "offTopicThreshold": number, "additionalRules": string? }?, "knownToolHandlerName": string?, "toolInvocationExplanations": boolean, "modelRoutingParameters": { "lowComplexityModelName": string, "lowComplexityModelReasoningEffort": string?, "mediumComplexityModelName": string, "mediumComplexityModelReasoningEffort": string?, "highComplexityModelName": string, "highComplexityModelReasoningEffort": string? }?, "additionalSettings": {}? } }{ "type": "object", "properties": { "name": { "type": "string" }, "parameters": { "type": "object", "properties": { "baseAddress": { "type": "string" }, "transportInterface": { "type": "string", "enum": [ "OpenAiCompatible", "OpenAiChatCompletions", "OpenAiResponses" ] }, "routingOption": { "type": "string", "enum": [ "Balanced", "Cheapest", "Fastest", "Quality" ] }, "skills": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } }, "hideToolsWithoutSkill": { "type": "boolean" }, "alwaysVisibleTools": { "type": "array", "items": { "type": "string" } }, "enableBash": { "type": "boolean" }, "includeWorkspaceInstructions": { "type": "boolean" }, "bashOptions": { "properties": { "fileSystem": { "properties": { "workingDirectory": { "type": "string" } }, "type": [ "object", "null" ] }, "allowDataPersistence": { "type": "boolean" }, "toolList": { "type": "array", "items": { "type": "string" } }, "toolExclusionMode": { "type": "string", "enum": [ "WhiteList", "BlackList" ] } }, "type": [ "object", "null" ] }, "knowledgeCollections": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } }, "rerankerName": { "type": [ "string", "null" ] }, "knowledgeBaseMaximumResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "knowledgeBaseMinimumScore": { "type": "number" }, "knowledgeUseReferences": { "type": "boolean" }, "knowledgeUseMetaDescriptions": { "type": "boolean" }, "queryStrategy": { "type": "string", "enum": [ "Plain", "Concatenate", "FullRewrite", "UserRewrite", "QueryFunction" ] }, "queryStrategyParameters": { "type": "object", "properties": { "rewriteContextSize": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "concatenateContextSize": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "apiKey": { "type": [ "string", "null" ] }, "modelName": { "type": "string" }, "temperature": { "type": [ "number", "null" ] }, "topP": { "type": [ "number", "null" ] }, "presencePenalty": { "type": [ "number", "null" ] }, "frequencyPenalty": { "type": [ "number", "null" ] }, "stop": { "type": [ "string", "null" ] }, "maxCompletionTokens": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "contextMaximumSize": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "contextOverflowAction": { "type": "string", "enum": [ "Throw", "Truncate", "TruncateHard", "Compact" ] }, "systemInstruction": { "type": [ "string", "null" ] }, "workerScriptSource": { "type": [ "string", "null" ] }, "userPromptTemplate": { "type": [ "string", "null" ] }, "assistantPrefill": { "type": [ "string", "null" ] }, "includePrefillingInMessages": { "type": "boolean" }, "reasoningEffort": { "type": [ "string", "null" ] }, "verbosity": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "NoSystemInstruct", "NoTemperature", "ThinkingProcess", "NoAssistantPrefilling", "ReturnReasoningTokens", "DisableMultiModalInput", "DiffusingStream", "OpenAiStrictJson", "StructuredOutputSupport", "PreserveThinkingTokens", "NoStopParameter", "NoReasoningEffort", "RewriteToolCallsAsUserMessages", "DisableReasoningSummary", "DisableReasoningDetails", "IncludeStoredReasoning", "StrictUserAssistantTurns" ] } }, "tools": { "type": [ "array", "null" ] }, "protocolFunctions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "callbackUrl": { "type": "string" }, "contentFormat": {} }, "required": [ "name", "description", "callbackUrl", "contentFormat" ] } }, "protocolFunctionSources": { "type": "array", "items": { "type": "string" } }, "mcpSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "systemInstructionsSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "enabledMultimodalFeatures": { "type": "array", "items": { "type": "string", "enum": [ "Image", "Audio", "Video", "File", "OtherFiles", "All" ] } }, "toolContextCount": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "sentinelOptions": { "properties": { "enabledFunctions": { "type": "array", "items": { "type": "string", "enum": [ "WebSearch", "Code", "OpenUrl", "Remember", "ImageGeneration", "XPostsSearch", "GenerateDocument", "GenerateWebPage", "AdvancedWebUsage", "Request", "Calendar" ] } } }, "type": [ "object", "null" ] }, "builtinFunctionsOptions": { "properties": { "webSearchMode": { "type": "string", "enum": [ "Full", "Summarized" ] }, "webSearchMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationQuality": { "type": "string", "enum": [ "Low", "Medium", "High", "Highest" ] }, "imageGenerationAllowMatureContent": { "type": "boolean" }, "imageGenerationAllowReferenceUsage": { "type": "boolean" }, "imageGenerationModelName": { "type": [ "string", "null" ] }, "includeAllMemoryContext": { "type": "boolean" }, "allowSharedMemory": { "type": "boolean" } }, "type": [ "object", "null" ] }, "moderationParameters": { "properties": { "violenceThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "sexualExplicitThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "politicalThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "dangerousContentThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "jailbreakThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "offTopicThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "additionalRules": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "knownToolHandlerName": { "type": [ "string", "null" ] }, "toolInvocationExplanations": { "type": "boolean" }, "modelRoutingParameters": { "properties": { "lowComplexityModelName": { "type": "string" }, "lowComplexityModelReasoningEffort": { "type": [ "string", "null" ] }, "mediumComplexityModelName": { "type": "string" }, "mediumComplexityModelReasoningEffort": { "type": [ "string", "null" ] }, "highComplexityModelName": { "type": "string" }, "highComplexityModelReasoningEffort": { "type": [ "string", "null" ] } }, "required": [ "lowComplexityModelName", "mediumComplexityModelName", "highComplexityModelName" ], "type": [ "object", "null" ] }, "additionalSettings": { "type": [ "object", "null" ] } }, "required": [ "baseAddress", "modelName" ] } } }
Responses:
- 200
The gateway configuration was saved.
Get/api/v1/ai-gateways/<id>View AI Gateway
View AI Gateway
Returns the gateway name, slug and full runtime parameters for one AI Gateway.
GET /api/v1/ai-gateways/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- id
Identifier of the AI Gateway to retrieve.
Responses:
- 200
Full AI Gateway configuration.
{ "message": null, "data": { "name": string, "slug": string, "parameters": { "baseAddress": string, "transportInterface": "OpenAiCompatible", "routingOption": "Balanced", "skills": [ "uuid", ... ], "hideToolsWithoutSkill": boolean, "alwaysVisibleTools": [ string, ... ], "enableBash": boolean, "includeWorkspaceInstructions": boolean, "bashOptions": { "fileSystem": { "workingDirectory": string }?, "allowDataPersistence": boolean, "toolList": [ string, ... ], "toolExclusionMode": "WhiteList" }?, "knowledgeCollections": [ "uuid", ... ], "rerankerName": string?, "knowledgeBaseMaximumResults": number, "knowledgeBaseMinimumScore": number, "knowledgeUseReferences": boolean, "knowledgeUseMetaDescriptions": boolean, "queryStrategy": "Plain", "queryStrategyParameters": { "rewriteContextSize": number, "concatenateContextSize": number }, "apiKey": string?, "modelName": string, "temperature": number?, "topP": number?, "presencePenalty": number?, "frequencyPenalty": number?, "stop": string?, "maxCompletionTokens": number?, "contextMaximumSize": number?, "contextOverflowAction": "Throw", "systemInstruction": string?, "workerScriptSource": string?, "userPromptTemplate": string?, "assistantPrefill": string?, "includePrefillingInMessages": boolean, "reasoningEffort": string?, "verbosity": string?, "flags": [ "NoSystemInstruct", ... ], "tools": [ ... ]?, "protocolFunctions": [ { "name": string, "description": string, "headers": {}, "callbackUrl": string, "contentFormat": any }, ... ], "protocolFunctionSources": [ string, ... ], "mcpSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "systemInstructionsSources": [ { "name": string, "description": string?, "url": string, "headers": {}, "cacheDuration": number }, ... ], "enabledMultimodalFeatures": [ "Image", ... ], "toolContextCount": number?, "sentinelOptions": { "enabledFunctions": [ "WebSearch", ... ] }?, "builtinFunctionsOptions": { "webSearchMode": "Full", "webSearchMaxResults": number, "imageGenerationMaxResults": number, "imageGenerationQuality": "Low", "imageGenerationAllowMatureContent": boolean, "imageGenerationAllowReferenceUsage": boolean, "imageGenerationModelName": string?, "includeAllMemoryContext": boolean, "allowSharedMemory": boolean }?, "moderationParameters": { "violenceThreshold": number, "sexualExplicitThreshold": number, "politicalThreshold": number, "dangerousContentThreshold": number, "jailbreakThreshold": number, "offTopicThreshold": number, "additionalRules": string? }?, "knownToolHandlerName": string?, "toolInvocationExplanations": boolean, "modelRoutingParameters": { "lowComplexityModelName": string, "lowComplexityModelReasoningEffort": string?, "mediumComplexityModelName": string, "mediumComplexityModelReasoningEffort": string?, "highComplexityModelName": string, "highComplexityModelReasoningEffort": string? }?, "additionalSettings": {}? } } }{ "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "parameters": { "type": "object", "properties": { "baseAddress": { "type": "string" }, "transportInterface": { "type": "string", "enum": [ "OpenAiCompatible", "OpenAiChatCompletions", "OpenAiResponses" ] }, "routingOption": { "type": "string", "enum": [ "Balanced", "Cheapest", "Fastest", "Quality" ] }, "skills": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } }, "hideToolsWithoutSkill": { "type": "boolean" }, "alwaysVisibleTools": { "type": "array", "items": { "type": "string" } }, "enableBash": { "type": "boolean" }, "includeWorkspaceInstructions": { "type": "boolean" }, "bashOptions": { "properties": { "fileSystem": { "properties": { "workingDirectory": { "type": "string" } }, "type": [ "object", "null" ] }, "allowDataPersistence": { "type": "boolean" }, "toolList": { "type": "array", "items": { "type": "string" } }, "toolExclusionMode": { "type": "string", "enum": [ "WhiteList", "BlackList" ] } }, "type": [ "object", "null" ] }, "knowledgeCollections": { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUID/GUID string" } }, "rerankerName": { "type": [ "string", "null" ] }, "knowledgeBaseMaximumResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "knowledgeBaseMinimumScore": { "type": "number" }, "knowledgeUseReferences": { "type": "boolean" }, "knowledgeUseMetaDescriptions": { "type": "boolean" }, "queryStrategy": { "type": "string", "enum": [ "Plain", "Concatenate", "FullRewrite", "UserRewrite", "QueryFunction" ] }, "queryStrategyParameters": { "type": "object", "properties": { "rewriteContextSize": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "concatenateContextSize": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } } }, "apiKey": { "type": [ "string", "null" ] }, "modelName": { "type": "string" }, "temperature": { "type": [ "number", "null" ] }, "topP": { "type": [ "number", "null" ] }, "presencePenalty": { "type": [ "number", "null" ] }, "frequencyPenalty": { "type": [ "number", "null" ] }, "stop": { "type": [ "string", "null" ] }, "maxCompletionTokens": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "contextMaximumSize": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "contextOverflowAction": { "type": "string", "enum": [ "Throw", "Truncate", "TruncateHard", "Compact" ] }, "systemInstruction": { "type": [ "string", "null" ] }, "workerScriptSource": { "type": [ "string", "null" ] }, "userPromptTemplate": { "type": [ "string", "null" ] }, "assistantPrefill": { "type": [ "string", "null" ] }, "includePrefillingInMessages": { "type": "boolean" }, "reasoningEffort": { "type": [ "string", "null" ] }, "verbosity": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "NoSystemInstruct", "NoTemperature", "ThinkingProcess", "NoAssistantPrefilling", "ReturnReasoningTokens", "DisableMultiModalInput", "DiffusingStream", "OpenAiStrictJson", "StructuredOutputSupport", "PreserveThinkingTokens", "NoStopParameter", "NoReasoningEffort", "RewriteToolCallsAsUserMessages", "DisableReasoningSummary", "DisableReasoningDetails", "IncludeStoredReasoning", "StrictUserAssistantTurns" ] } }, "tools": { "type": [ "array", "null" ] }, "protocolFunctions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "callbackUrl": { "type": "string" }, "contentFormat": {} }, "required": [ "name", "description", "callbackUrl", "contentFormat" ] } }, "protocolFunctionSources": { "type": "array", "items": { "type": "string" } }, "mcpSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "systemInstructionsSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "cacheDuration": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 } }, "required": [ "name", "url" ] } }, "enabledMultimodalFeatures": { "type": "array", "items": { "type": "string", "enum": [ "Image", "Audio", "Video", "File", "OtherFiles", "All" ] } }, "toolContextCount": { "minimum": -2147483648, "maximum": 2147483647, "type": [ "integer", "null" ] }, "sentinelOptions": { "properties": { "enabledFunctions": { "type": "array", "items": { "type": "string", "enum": [ "WebSearch", "Code", "OpenUrl", "Remember", "ImageGeneration", "XPostsSearch", "GenerateDocument", "GenerateWebPage", "AdvancedWebUsage", "Request", "Calendar" ] } } }, "type": [ "object", "null" ] }, "builtinFunctionsOptions": { "properties": { "webSearchMode": { "type": "string", "enum": [ "Full", "Summarized" ] }, "webSearchMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationMaxResults": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "imageGenerationQuality": { "type": "string", "enum": [ "Low", "Medium", "High", "Highest" ] }, "imageGenerationAllowMatureContent": { "type": "boolean" }, "imageGenerationAllowReferenceUsage": { "type": "boolean" }, "imageGenerationModelName": { "type": [ "string", "null" ] }, "includeAllMemoryContext": { "type": "boolean" }, "allowSharedMemory": { "type": "boolean" } }, "type": [ "object", "null" ] }, "moderationParameters": { "properties": { "violenceThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "sexualExplicitThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "politicalThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "dangerousContentThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "jailbreakThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "offTopicThreshold": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "additionalRules": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "knownToolHandlerName": { "type": [ "string", "null" ] }, "toolInvocationExplanations": { "type": "boolean" }, "modelRoutingParameters": { "properties": { "lowComplexityModelName": { "type": "string" }, "lowComplexityModelReasoningEffort": { "type": [ "string", "null" ] }, "mediumComplexityModelName": { "type": "string" }, "mediumComplexityModelReasoningEffort": { "type": [ "string", "null" ] }, "highComplexityModelName": { "type": "string" }, "highComplexityModelReasoningEffort": { "type": [ "string", "null" ] } }, "required": [ "lowComplexityModelName", "mediumComplexityModelName", "highComplexityModelName" ], "type": [ "object", "null" ] }, "additionalSettings": { "type": [ "object", "null" ] } }, "required": [ "baseAddress", "modelName" ] } } }
Delete/api/v1/ai-gateways/<id>Delete AI Gateway
Delete AI Gateway
Deletes one AI Gateway owned by the authenticated account.
DELETE /api/v1/ai-gateways/<id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- id
Identifier of the AI Gateway to delete.
Responses:
- 200
The AI Gateway was deleted.
Accounts
Put/api/v1/accountsUpdate Account
Update Account
Replaces the authenticated account display name and account-level parameters.
PUT /api/v1/accountsHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
Full account update payload. The parameters object replaces the current account parameters.
{ "name": string, "parameters": { "allowConversationsLogging": boolean, "automaticJsonHealing": boolean, "allowSemanticDataCollection": boolean, "notifications": { "emails": [ string, ... ], "lowBalance": { "enabled": boolean, "threshold": number }, "deprecatedModels": { "enabled": boolean }, "weeklyTestingSummary": boolean, "repeatedTestFailures": boolean } } }{ "type": "object", "properties": { "name": { "type": "string" }, "parameters": { "type": "object", "properties": { "allowConversationsLogging": { "type": "boolean" }, "automaticJsonHealing": { "type": "boolean" }, "allowSemanticDataCollection": { "type": "boolean" }, "notifications": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "lowBalance": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold": { "type": "number" } } }, "deprecatedModels": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "weeklyTestingSummary": { "type": "boolean" }, "repeatedTestFailures": { "type": "boolean" } } } } } } }
Responses:
- 200
The account name and parameters were saved.
- 400
Invalid request body.
Post/api/v1/accounts/roll-saltRoll Salt
Roll Salt
Generates a new random salt for the account, invalidating webhooks and integrations that depend on the previous salt.
POST /api/v1/accounts/roll-saltHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
Salt rolled successfully.
Get/api/v1/accounts/agent-setup-promptGet Agent Setup Prompt
Get Agent Setup Prompt
Generates a setup prompt URL for configuring an agent to use the authenticated account.
GET /api/v1/accounts/agent-setup-promptHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
A setup prompt URL for the authenticated account.
{ "message": null, "data": { "setupPrompt": "Follow instructions from https://..." } } - 429
The hourly setup prompt generation limit was exceeded.
API Keys
Get/api/v1/accounts/api-keyList API Keys
List API Keys
Returns masked private and public API keys for the authenticated account, plus the current account salt used by webhook and integration signatures.
GET /api/v1/accounts/api-keyHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Responses:
- 200
List of API keys and account salt.
{ "message": null, "data": { "apiKeys": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "expiresAt": "2027-01-01T00:00:00Z", "usedAt": "2026-03-01T12:00:00Z", "label": "My key", "key": "...abc123" } ], "salt": "randomsaltvalue" } }
Post/api/v1/accounts/api-keyCreate API Key
Create API Key
Creates a private or public API key for the authenticated account and returns the grant key once.
POST /api/v1/accounts/api-keyHeaders:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Request examples:
API key creation payload. The type field accepts private or public.
{ "label": string, "duration": number, "type": string }{ "type": "object", "properties": { "label": { "type": "string" }, "duration": { "type": "number" }, "type": { "type": "string" } } }
Responses:
- 200
API key created successfully.
{ "message": null, "data": { "grantKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } - 400
Invalid request body.
Delete/api/v1/accounts/api-key/<key-id>Delete API Key
Delete API Key
Revokes an API key owned by the authenticated account.
DELETE /api/v1/accounts/api-key/<key-id>Headers:
- AuthorizationRequired
The API key used to authenticate the request. Can be provided as a query parameter (
api-key).
Path parameters:
- key-iduuid
Unique identifier of the API key to delete.
Responses:
- 200
API key deleted successfully.
- 400
API key not found or does not belong to the account.
Data structures
API entities
System.IO.StreamWriter