API Documentation
Build, deploy, and observe Ainvented agents with a clear REST API. Start with one request, then add sessions, tools, files, tasks, and production controls as you need them.
Send your first message
Create an API key, keep it on your server, and make one chat-completion request.
- 1Create a key
Open API Key Management and copy your key once. Never expose it in browser code.
- 2Call the API from your server
export API_KEY="your_api_key_here" curl https://ainvented.com/api/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "Hello from Ainvented"}] }' - 3Read the answer
The generated text is in
choices[0].message.content. Save the returnedsession_idwhen you want Ainvented to maintain conversation history.
Introduction
The Ainvented REST API gives your applications programmatic access to agents and their projects through a consistent interface. Use familiar HTTP patterns while Ainvented manages model access, sessions, tools, context, and observability.
- API origin
https://ainvented.com- Authentication
- A Bearer API key, sent from your server. Two key scopes.
- Format
- JSON in, JSON out. Streaming answers arrive as server-sent events.
- Errors
- One envelope for every failure. Error codes.
- Chat CompletionsGenerate text, stream it, keep sessions, pick a tier, run tools.
- TasksReusable jobs that read a conversation and return structured data.
- Multimodal ContentImages and audio in messages, generated images in responses.
- Voice18 callsNatural speech, voices designed or cloned, and transcripts — on their own or in voice projects.
- Execute WorkflowRun a workflow project with inputs and read its output by node.
- Projects8 callsCreate projects, set budgets and quotas, pick defaults.
- Payments6 callsCharge your end-clients and top up balances or project budgets.
- WhatsApp22 callsConnect a customer’s WhatsApp number to a project; reply with the assistant or from your app; manage templates; read traffic everywhere.
- Project API keys3 callsMint, list and revoke keys that are bound to one project.
- Consumption1 callTokens and cost per project, broken down by what consumed them.
- Promotions3 callsPromo codes and referral links.
- Vector Stores4 callsStore documents, search them semantically, optionally get a generated answer.
- Webhooks5 callsSigned HTTPS notifications for budget, token and usage events.
- Error CodesThe one error envelope and every status you can get back.
- Best PracticesKeys, retries, sessions, streaming, timeouts.
- Additional ResourcesWhere to go next.
Authentication
Ainvented v1 API requests use Bearer tokens unless an endpoint is explicitly marked public or browser-session only. Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYAdmin keys vs project-scoped keys
Every API key has one of two scopes. The scope is fixed at creation time and determines what the key can do.
/v1/projects — listing, reading, updating, deleting, minting per-project keys, configuring webhooks, viewing consumption, and the partner payment surface (payments, payment methods, auto-recharge). /v1/chat/completions, /v1/tasks, /v1/vector-stores, /v1/workflows — which silently resolve to the bound project. Cannot read or modify anything under /v1/projects(no list, read, update, delete, key management, webhooks, consumption, or billing). Intended for partner-enabled accounts to give their clients a key that uses the product without exposing the project-management surface.Rate Limits
API requests are rate limited using a token bucket algorithm. Rate limit information is included in response headers:
X-RateLimit-Limit: Maximum requests per time windowX-RateLimit-Remaining: Requests remaining in current windowX-RateLimit-Reset: Unix timestamp when limit resets
When rate limited, the API returns a 429 Too Many Requests response with a Retry-After header indicating seconds until reset.
Request Tracing & Observability
Every response from POST /v1/chat/completions — success or error, streaming or non-streaming — includes an X-Request-Id header (UUID). This id correlates the request with its usage events and, when the project is attached to an Observability project, with its captured trace. The header is purely additive — request and response bodies are unchanged.
- Attach a chat project to an Observability project (sidebar → Observability) to see per-request traces: prompt, completion, model, tokens, cost, latency, TTFT and status.
- Trace capture runs after the response is sent and never adds latency to your requests.
- LLM-as-a-judge evaluations run against your project budget and appear in the project's consumption ledger like any other usage.
List Models
List the model tiers this account can use. Uses the standard list-models shape, so a compatible client library or model picker populates itself with no Ainvented-specific code.
Authentication
Bearer token required in Authorization header
Response Schema
JSON type shape
{
"object": "string",
"data": [
{
"id": "string",
"object": "string",
"created": "number",
"owned_by": "string"
}
]
}Fields6
objectdataidobjectcreatedowned_byCode Examples
Every tier you may pass as `model`
curl https://ainvented.com/api/v1/models \
-H "Authorization: Bearer $API_KEY"
# {
# "object": "list",
# "data": [
# { "id": "ainvented-default", "object": "model", "created": 1735689600, "owned_by": "ainvented" },
# { "id": "ainvented-low", "object": "model", "created": 1751328000, "owned_by": "ainvented" },
# { "id": "ainvented-saga", "object": "model", "created": 1783036800, "owned_by": "ainvented" },
# { "id": "ainvented-epic", "object": "model", "created": 1783036800, "owned_by": "ainvented" }
# ]
# }Returns a single model object, or 404 if the tier is not available to you
curl https://ainvented.com/api/v1/models/ainvented-low \
-H "Authorization: Bearer $API_KEY"
# { "id": "ainvented-low", "object": "model", "created": 1751328000, "owned_by": "ainvented" }
# An unavailable or unknown name returns 404:
# { "error": { "message": "The model 'not-a-tier' does not exist",
# "type": "invalid_request_error", "param": "model", "code": "model_not_found" } }Populate a model picker from the live list
import requests
BASE = "https://ainvented.com/api/v1"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
models = requests.get(f"{BASE}/models", headers=headers).json()
for m in models["data"]:
print(m["id"]) # ainvented-default, ainvented-low, ainvented-saga, ainvented-epic
one = requests.get(f"{BASE}/models/ainvented-epic", headers=headers).json()
print(one["owned_by"]) # ainvented
# Any standard chat-completions client library works too: point its base URL at
# BASE and its "list models" call returns exactly the tiers above.Details
Create Chat Completion
Generate a chat completion response using your configured chat project. Supports both streaming and non-streaming modes.
Authentication
Bearer token required in Authorization header
Request Schema
JSON type shape
{
"model": "string",
"messages": [
{
"role": "string",
"content": "string | ContentPart[]"
}
],
"temperature": "number",
"max_tokens": "number",
"reasoning_effort": "string",
"response_format": "object",
"include_reasoning": "boolean",
"reasoning": "object",
"system_authority": "string",
"stream": "boolean",
"stream_options": "object",
"project_id": "string",
"safety_identifier": "string",
"prompt_cache": "boolean",
"prompt_cache_ttl_hours": "string|integer",
"session_id": "string",
"run_workflow": "boolean",
"tools": "array",
"modalities": "array",
"image": "object",
"connector_id": "string",
"connector_to": "string",
"connector_media_type": "string",
"connector_media_url": "string",
"connector_media_filename": "string",
"connector_email_subject": "string",
"tool_choice": "string|object"
}Fields29
modelmessagesrolecontenttemperaturemax_tokensreasoning_effortresponse_formatinclude_reasoningreasoningsystem_authoritystreamstream_optionsproject_idsafety_identifierprompt_cacheprompt_cache_ttl_hourssession_idrun_workflowtoolsmodalitiesimageconnector_idconnector_toconnector_media_typeconnector_media_urlconnector_media_filenameconnector_email_subjecttool_choiceResponse Schema
JSON type shape
{
"id": "string",
"object": "string",
"created": "number",
"model": "string",
"choices": [
{
"index": "number",
"message": {
"role": "string",
"content": "string | null",
"tool_calls": "array (only when the model calls inline function tools)",
"reasoning_content": "string (only with include_reasoning: true, and only when the model reasoned)"
},
"finish_reason": "string"
}
],
"usage": {
"prompt_tokens": "number",
"completion_tokens": "number",
"total_tokens": "number",
"prompt_tokens_details": "object",
"completion_tokens_details": "object"
},
"response": {
"images": "string[]",
"image_meta": "object[] (only present when images were produced)"
},
"session_id": "string",
"context_truncation": "object (present ONLY when part of the request had to be left out)"
}Fields23
idobjectcreatedmodelchoicesindexmessagerolecontenttool_callsreasoning_contentfinish_reasonusageprompt_tokenscompletion_tokenstotal_tokensprompt_tokens_detailscompletion_tokens_detailsresponseimagesimage_metasession_idcontext_truncationCode Examples
Basic completion request with non-streaming response
import requests
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"messages": [
{"role": "user", "content": "Hello, how are you?"}
],
"temperature": 0.7,
"max_tokens": 150
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])Streaming completion with Server-Sent Events
import json
import requests
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"messages": [
{"role": "user", "content": "Tell me a story"}
],
"stream": True
}
response = requests.post(url, headers=headers, json=data, stream=True)
response.raise_for_status()
for line in response.iter_lines():
if not line.startswith(b"data: "):
continue
payload = line[6:]
if payload == b"[DONE]":
break
chunk = json.loads(payload)
content = chunk["choices"][0]["delta"].get("content")
if content:
print(content, end="", flush=True)Basic cURL example
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "Hello!"}
],
"temperature": 0.7
}'Using fetch API
const apiKey = "your_api_key_here";
const url = "https://ainvented.com/api/v1/chat/completions";
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
messages: [
{ role: "user", content: "Hello, how are you?" }
],
temperature: 0.7,
max_tokens: 150
})
});
const result = await response.json();
console.log(result.choices[0].message.content);Details
Model tiers
Select the chat model per request with the model field (or set a project default via preconfigured_model):
ainvented-default— the standard model.ainvented-low— a lower-cost model. Best for high-volume, cost-sensitive turns.ainvented-saga— an advanced reasoning model. Best for complex analysis and long-form work.ainvented-epic— the highest-capability model. Best for the hardest reasoning tasks.ainvented-liteandliteare additional names for the standard tier — same routing, same price asainvented-default.- The bare words
low,saga,epic,liteanddefaultare accepted too (case-insensitively), for clients whose settings offer a single free-text "Model ID" box.GET /api/v1/models/{id}accepts every one of these spellings and resolves it to the canonical entry. - Omitting
modeluses the project's preconfigured default (orainvented-default). Any unrecognized value is accepted and treated asainvented-default— never rejected. - The response
modelfield echoes the canonical name of the tier you selected —epiccomes back asainvented-epic, never your raw string.GET /api/v1/modelsis the authoritative list. Per-tier pricing is on the pricing page.
Select how much reasoning each request gets with the reasoning_effort field (or set a project default via preconfigured_effort): low, medium, high, xhigh or max. Omitting it keeps the tier's standard effort, so a higher effort is always something you opt into — it buys answer quality with time-to-first-token and completion tokens. It applies identically to streaming and non-streaming requests.
- The same five levels work on every tier — each is mapped onto what the serving model actually supports, so you never have to know which engine is behind a tier.
- For drop-in compatibility,
reasoning_effort: "minimal"and"none"are also accepted and treated aslow, and an explicitnullis treated as if the field were omitted — so a request written against a standard chat-completions client works unchanged. - Any other value returns
400 invalid_request_errorwithparam="reasoning_effort". It is rejected before the request reaches a model, so an invalid value never costs you anything. - Reasoning tokens are billed inside
completion_tokens— never as an extra charge — and are reported underusage.completion_tokens_details.reasoning_tokenswhen the serving model breaks them out. - A higher effort spends more of the same
max_tokensbudget thinking, so a capped request can return less visible text atmaxthan atlow. Raisemax_tokensalongside the effort.
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"model":"ainvented-low",
"messages":[{"role":"user","content":"Summarize: the meeting is moved to 3pm Friday."}]}'
# -> response.model echoes the requested tier; a text-only, in-budget turn is served + billed as ainvented-lowStreaming Response
When stream: true is set, the response uses Server-Sent Events (SSE). Each chunk follows this schema:
{
"id": "string - Unique completion ID",
"object": "string - 'chat.completion.chunk'",
"created": "number - Unix timestamp",
"model": "string - Model used",
"choices": [
{
"index": "number - Choice index",
"delta": {
"role": "string (optional) - 'assistant' (first chunk only)",
"content": "string (optional) - Incremental text content",
"reasoning_content": "string (optional) - Incremental reasoning, streamed BEFORE the answer while the model thinks (on by default for streams; include_reasoning: false turns it off). Comes in its own chunks — never in the same chunk as `content` — so a client that ignores unknown delta keys sees exactly the stream it always did.",
"tool_calls": "array (optional) - Inline function-calling deltas: [{ index: number, id: string, type: 'function', function: { name: string, arguments: string } }]. Accumulate by `index`; the stream ends with a finish_reason 'tool_calls' chunk.",
"images": "string[] (optional) - Emitted in a dedicated chunk when the model generates one or more images. URLs (or data: URLs). Never inlined as markdown in delta.content.",
"image_meta": "object[] (optional) - Emitted IMMEDIATELY AFTER the delta.images chunk when the caller opted in via modalities/image. Same per-entry shape as response.image_meta (url, size, format, bytes, source, request_id, prompt_excerpt). Old clients can safely ignore unknown delta.* keys."
},
"finish_reason": "string | null - 'stop' (final text chunk), 'tool_calls' (after inline function-call deltas), else null"
}
],
"session_id": "string (final chunk only) - Session ID for future requests",
"context_truncation": "object (final chunk only, and only when part of the request had to be left out) - Same shape as the non-streaming `context_truncation` field. It rides the FINAL chunk because the upstream reports the trim after the generated text."
}Streaming reasoning
On a reasoning turn the model can think for a while before the first word of the answer. A stream (stream: true) now carries that reasoning as it happens, in delta.reasoning_contentchunks, followed by the answer in delta.content as always — the convention coding agents and chat clients already render as "thinking". Nothing to enable.
- Turn it off per request with
include_reasoning: false(orreasoning: {"exclude": true}). Off, the stream is exactly what it was before. - Non-streaming requests return reasoning only when asked:
include_reasoning: trueaddschoices[0].message.reasoning_content. - Reasoning is never part of
content, never stored with the session, and never changes the bill: reasoning tokens were always counted insidecompletion_tokens(usage.completion_tokens_details.reasoning_tokens). - A turn whose model does not reason (low effort, a short answer) has no reasoning chunks. A higher
reasoning_effortproduces more of them. - While a stream has sent nothing for 15 seconds — a model thinking silently — an SSE comment line
: keep-aliveis written so proxies and client idle timers keep the connection open. Every SSE parser ignores comment lines.
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"The user wants the total. 3 boxes of 12 is 36…"},"finish_reason":null}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"There are 36 items."},"finish_reason":null}]}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]Structured output (response_format)
Ask for JSON and get JSON. response_format takes the standard three forms and works on every tier — including the backup model behind each tier — streaming or not:
{"type": "text"}— the default. The request is handled exactly as if the field were absent.{"type": "json_object"}— the reply is one valid JSON object. Describe the keys you want in your messages.{"type": "json_schema", "json_schema": {"name": …, "schema": {…}, "strict": true}}— the reply validates against your JSON Schema (types, required keys, enums, nested objects and arrays). Strict schemas follow the usual rules: every property listed inrequiredandadditionalProperties: falseon each object; a schema that breaks them is a400 invalid_response_format(param: response_format) that names every problem found — up to five, with where each is — so you fix them in one go. Withstrictfalse or omitted the schema guides the reply and you are guaranteed a valid JSON object.
Every reply is checked before it is released. A reply that does not match is generated again — a bounded number of times — and if none matches the request fails with 502 response_format_failed (retryable). The generations that were made are billed like any other turn; a request that is refused before reaching a model (an invalid response_format) costs nothing.
- Streaming: the JSON arrives as ordinary
delta.contentchunks. Accumulate them and parse at the end. - With tools: the model may still call a tool; you get
tool_callsas usual and any prose next to the call is dropped, socontentis always JSON ornull. - max_tokens: your cap wins over the JSON: a reply that does not fit is cut at the cap with
finish_reason: "length"(incomplete JSON, billed at most the cap). Leave room. - Images:
modalities: ["image"](image-only) cannot be combined with a JSON format — 400. - The JSON is returned byte-for-byte as generated: no footer, link rewriting or truncation notes are added to a JSON reply.
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"model":"ainvented-low",
"messages":[{"role":"user","content":"Ana Gómez, 34, lives in Bogotá and works as an architect."}],
"response_format":{"type":"json_schema","json_schema":{"name":"person","strict":true,
"schema":{"type":"object","additionalProperties":false,
"required":["name","age","city"],
"properties":{"name":{"type":"string"},"age":{"type":"integer"},"city":{"type":"string"}}}}}}'
# -> choices[0].message.content = {"name":"Ana Gómez","age":34,"city":"Bogotá"}Coding agents & other standard chat-completions clients
This endpoint is a drop-in target for any client that speaks the standard chat-completions protocol. Point the client's Base URL at https://ainvented.com/api/v1, paste an API key, and set the Model ID to one of the tiers above.
Agent clients differ from chat clients in one way that matters: they ship a largesystem prompt that defines a strict response protocol — "every reply must be exactly one tool call", replies formatted as tagged blocks — and they reject any reply that does not follow it, re-sending the whole conversation as a retry. For those clients the caller's system prompt must be the only thing shaping the answer, and it is:
- Whenever a request carries a
systemmessage, that message is authoritative: the platform's conversational framing and tone rules are not layered on top of it. You do not have to ask for this and there is nothing to configure. - Your project's configured agent prompt still applies, ahead of your per-request instructions, so anything you set up in the project is preserved and your request wins on any point the two disagree about.
- Native function
toolswork exactly as before, andtool_callscome back in the usual shape — the two are independent. - Send
system_authority: "merge"on a request to pin the previous behaviour.
Screenshots and other images an agent attaches are accepted as image_url content parts in JPEG, PNG, GIF, WebP, BMP, TIFF or AVIF (an editor or browser screenshot is usually WebP). An unsupported format is a 400, not a retryable error — retrying the same image will not help; convert it first.
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"model":"ainvented-epic",
"stream":true,
"stream_options":{"include_usage":true},
"messages":[
{"role":"system","content":"You are an agent. Every reply MUST be exactly one <tool> block and nothing else."},
{"role":"user","content":"List the files in the project root."}
]}'Session Management
Use the session_id parameter to maintain conversation context across requests:
- First request — omit
session_id; the response returns a new session ID. - Subsequent requests — include that
session_idto continue the conversation. - Sessions are tied to your API key and keep the full conversation history.
- Two ways to do multi-turn — pick one, don't combine them:
- Stateless (recommended) — send the entire
messagesarray (all prior turns + the new one) on every request. Your transcript IS the conversation history; the server does not add any stored history on top of it. - Stateful — send only the latest user message in
messagesplus thesession_id; the server supplies the earlier turns from its store.
- Stateless (recommended) — send the entire
- You don't need to do both: if
messagesalready contains prior turns, the server automatically will not also re-load the stored session history, so context is never duplicated or double-counted toward usage. (Sending the full transcript AND relying on the stored history would otherwise repeat the same turns.) /v1/chat/completionsdoes not generate or expose chat session titles. (Title generation is suppressed upstream to minimize latency and cost.) Use thesession_idreturned in the response to correlate multi-turn conversations.
Project Selection
The API determines which project to use in this priority order:
- The API key's associated project (if scoped) — takes precedence over everything else.
- The
project_idrequest field — only when the key is not scoped to a project. - Your default project (first created).
Project Enhancements: Skills & Guardrails
Every request automatically inherits the active Skills and Guardrails configured for the project in the AI Chat UI — injected as system context on every call, with no extra request fields.
🎯 Skills
Instruction presets that shape the AI's behaviour on every response (e.g. "always respond in bullet points"). Set via the Skills button in AI Chat.
🛡️ Guardrails
Content/tone rules that are always enforced (e.g. "never mention competitors"). Set via the Guardrails button in AI Chat.
Workflow Execution in Chat
Set run_workflow: true to run the project's configured workflow before the AI responds. The workflow output is injected as context so the AI can reason over real-time data from your pipeline.
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "Summarise the latest results"}
],
"run_workflow": true
}'import requests
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
# run_workflow: true triggers the project workflow before the AI responds.
# The workflow output is injected as context so the AI can reason over real data.
data = {
"messages": [
{"role": "user", "content": "Summarise the latest results"}
],
"run_workflow": True
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])Tools Override (Selective Workflow Execution)
By default, all active project workflows run on every request and their output is injected as context. Use the tools field to control which run:
Default
No tools field → all active workflows auto-run (same as the chat UI).
Override
A tools array of names → only matching workflows run. Names look like workflow_<name>.
Disable
Pass "tools": [] → no workflows run for this request. Skills and guardrails still apply.
# Only execute specific workflows (override mode)
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "tell me about Croatia"}
],
"tools": [
{"type": "function", "function": {"name": "workflow_country_cities"}}
]
}'import requests
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
# Override mode: only execute specific workflow tools
# Pass an empty tools array to disable all workflow execution
data = {
"messages": [
{"role": "user", "content": "tell me about Croatia"}
],
"tools": [
{"type": "function", "function": {"name": "workflow_country_cities"}}
]
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])Tasks — async history analysis
Tasks are reusable, client-defined units that asynchronously analyze a conversation's history to extract structured data or classify intent — without ever affecting the chat reply's latency. A task is an instruction prompt + a JSON-Schema output_schema + a trigger. Manage them via the REST endpoints below, and select them per interaction with the completions tools/tool_choice params (a task is a function tool referenced by name). Available when the Tasks feature is enabled for your project.
Endpoints
/api/v1/tasksname, instructions, trigger_type, output_schema, and optional trigger_config, history_scope, model, action, enabled, scope. model is the tier the task's runs are served on (ainvented-default, ainvented-low, ainvented-saga or ainvented-epic, aliases accepted as on /v1/chat/completions); omitted, the project's preconfigured_model applies, then the standard tier. Runs use the project's preconfigured_effort. (See Triggers and Limits below.)/api/v1/tasksstatus, trigger_type, enabled, limit, after. Your global tasks are included by default — pass ?include_global=false for project-only, or ?scope=global for globals only. Each task carries scope./api/v1/tasks/{id}/api/v1/tasks/{id}enabled./api/v1/tasks/{id}/api/v1/tasks/{id}/runresult. Body: messages?, session_id?, project_id?. Used by the tool_call delivery mode and for run-now / testing. Runs regardless of the task's enabled flag (manual operator override — enabled:false only pauses automatic triggers); the run is billed and audited normally./api/v1/tasks/{id}/runsresult, status, confidence, request_id, source_session_id, prompt_tokens/completion_tokens, completed_at. Filter to one conversation with ?session_id=…. (See Reading results.)Triggers
A task's trigger_type decides when it can run:
manual— only runs when you explicitly name it (intools) or call/run.on_message— auto-runs on each interaction undertool_choice:'auto'(or on every request when transparent auto-fire is enabled for the project).on_intent—trigger_config: { intents: [...] }. Undertool_choice:'auto'(or transparent auto-fire) the task auto-fires when the conversation matches one of its declared intents (e.g.cancel_order,refund). You can also name it explicitly intoolsto force it on any turn.schedule—trigger_config: { cron, timezone?, session_id? }.
Scope — project vs. global
scope defaults to 'project'. Set it to 'global' to make the task available to all of your projects (it's user-scoped, so project_id is null).
Selecting tasks from a completion
Name a task as a function tool — "tools":[{"type":"function","function":{"name":"<task name>"}}] — controlled by tool_choice (auto / none / required / {type:'function',function:{name}}). With both tools and tool_choice omitted, no tasks run by default (the cost-safe default). The project is resolved from your API key (or the project_id field) exactly like the rest of the endpoint — you never put a project id inside tools, and a task name resolves within the resolved project.
Inline function tools (standard function calling)
Separate from stored Tasks, you can use standard function calling: pass full function definitions inline on every request and let the model decide when to call them. Nothing is stored — if you don't send a definition on a request, it doesn't exist for that request.
- Define functions in
tools:{type:"function", function:{name, description, parameters /* JSON Schema */}}. tool_choice:auto(model decides),none(never call),required(must call one), or{type:"function",function:{name}}(force one).- When the model calls a function, the reply has
finish_reason:"tool_calls",message.content:null, andmessage.tool_calls[](each withfunction.argumentsas a JSON string). Parallel calls are supported. - You execute the function and continue the standard loop: resend with the prior
{role:"assistant", tool_calls:[…]}and a{role:"tool", tool_call_id, name, content}result. The model then answers using the result. - Works with
stream:true(tool calls arrive asdelta.tool_callsthen a finalfinish_reason:"tool_calls"chunk).
# 1) Model decides to call get_weather
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"model":"ainvented-default",
"messages":[{"role":"user","content":"Weather in Paris?"}],
"tools":[{"type":"function","function":{"name":"get_weather",
"description":"Get current weather",
"parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}],
"tool_choice":"auto"}'
# -> finish_reason "tool_calls"; message.tool_calls[0].function.arguments is a JSON string
# 2) Run the function yourself, then send the result back to finish the turn
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"model":"ainvented-default","messages":[
{"role":"user","content":"Weather in Paris?"},
{"role":"assistant","content":null,"tool_calls":[{"id":"call_1","type":"function",
"function":{"name":"get_weather","arguments":"{\"city\":\"Paris\"}"}}]},
{"role":"tool","tool_call_id":"call_1","name":"get_weather","content":"18C, sunny"}]}'
# -> a normal answer that uses "18C, sunny"Result-delivery modes
How you get a task result back from /chat/completions:
Reading results & delivery (action)
After a completion selects a task, poll GET /api/v1/tasks/{id}/runs?session_id=… using the session_id the completion returned (it matches the run's source_session_id). A run with status:"success" is done. A run stuck running past ~10 min is auto-failed to error (timed_out) — just re-trigger.
Or have the result pushed when the run finishes via the task's action:
action.webhook_url— POSTs the structured payload (must be a public http(s) URL; private/loopback/metadata addresses are rejected for SSRF safety).action.connector_id+action.connector_to— sends via a project chat connector (Telegram / WhatsApp / SMS / Email / Gmail / SMTP).action.min_confidence— gates delivery (results below it are stored but not pushed).
Webhook takes precedence when both are set; delivery is best-effort and never affects the stored run. The delivered flag on each run reflects the outcome.
history_scope & limits
history_scope controls how much of the conversation the task reads:
{ mode: 'full' }(default) — the entire transcript, with automatic map-reduce over long histories (bounded to the most recent ~144k tokens to cap per-run cost).{ mode: 'last_n', n: <1..1000> }— only the last N messages.{ mode: 'since', since: '<ISO>' }— falls back tofullfor the standard message shape (no per-message timestamps).
Limits: name ≤120 chars, unique per project (or per account for global tasks) and not a reserved name like image_generation; on a name clash the project-local task wins for that project. instructions ≤20000 chars; metadata ≤16 keys; output_schema nesting ≤32 levels. Unknown fields are rejected (strict).
Cost & quotas
Every task AI call is metered (one usage event per AI call); CRUD makes no AI call. Per-project guardrails cap active tasks and runs per minute & per day — over the cap, runs are skipped (no spend) and task creation returns 429 task_quota_exceeded.
Each run carries the tokens it was charged for on prompt_tokens and completion_tokens, so GET /api/v1/tasks/{id}/runs reconciles 1:1 with what the project's consumption reports for those runs. A run that never reached the model — refused by the budget gate, or a task that no longer exists — reports 0, which is exactly what it cost. A retried run reports the sum of its attempts.
Error codes
feature_disabled (403) — Tasks not enabled for this project.task_not_found (404) — task id not found / not owned by your project.invalid_request_error (400) — bad payload, invalid output_schema / cron / trigger_config. Includes schedule_disabled (schedule trigger is off) and invalid_schedule_scope (a global task can't use the schedule trigger).task_quota_exceeded (429) — active-task cap reached.duplicate_task_name (409) — a non-deleted task with that name already exists in the same scope (per project, or per account for global tasks). A deleted task's name becomes reusable.Multimodal Content Support
The Chat Completions API supports multimodal content including base64-encoded images and audio files. You can send images and audio alongside text in your messages using the ContentPart array format.
Image Generation — Request
Image output is opt-in per request: add "image" to modalities (or a tool named image_generation) and describe the picture in the last user message. Everything else is the same chat-completions call, so any standard chat-completions SDK works unchanged. Size, quality and count live in the optional image block; anything you leave out falls back to the project's image defaults (the chat's Configure pane), then to 1024x1024, standard, one image.
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{
"modalities": ["image"],
"image": { "size": "1024x1536", "quality": "standard" },
"messages": [{"role": "user", "content": "A minimalist poster of a cat astronaut floating above the Moon, flat colors"}]
}'
# -> choices[0].message.content is a short note ("Generated 1 image."),
# response.images[0] is the picture, usage counts the image tokens (see below)const res = await client.chat.completions.create({
model: 'ainvented-default',
modalities: ['image'],
image: { size: '1024x1536' }, // optional: size, quality ('standard' | 'hd'), n (1-4)
messages: [{ role: 'user', content: 'A minimalist poster of a cat astronaut floating above the Moon' }],
});
const [picture] = res.response.images; // an https:// or data: URL — accept both
console.log(res.usage.completion_tokens_details.image_tokens);res = client.chat.completions.create(
model="ainvented-default",
extra_body={"modalities": ["image"], "image": {"size": "1024x1536"}},
messages=[{"role": "user", "content": "A minimalist poster of a cat astronaut floating above the Moon"}],
)
picture = res.model_extra["response"]["images"][0] # an https:// or data: URL
print(res.usage.completion_tokens_details.image_tokens)image.size:256x256,512x512,1024x1024,1024x1536,1536x1024,1024x1792or1792x1024— the picture comes back at exactly that size.quality:standardorhd(more detail, more output tokens).n: 1 to 4 pictures per call.- Reference images: attach pictures as
image_urlparts of the last user message and the model edits or uses them (a product shot, a logo) instead of inventing one; their input tokens are billed at the image-input rate. - Usage: an image turn's
usagecounts the pictures too — insideprompt_tokens/completion_tokens, itemised asprompt_tokens_details.image_tokensandcompletion_tokens_details.image_tokens— so what you read there is what the ledger charged. A text turn'susageis unchanged. - Where the picture is:
response.images(or the streamingdelta.imageschunk). Each entry is a URL your client can load or fetch: today an inlinedata:image/png;base64,…URL for bothresponse_formatvalues, so treathttps://anddata:alike. A 1024² standard image answers in about 12 s, an hd portrait in about 25 s. image.remove_backgroundanswers a transparent PNG when background removal is enabled for the deployment; otherwise the flag is accepted and ignored.
Image Generation — Response Shape
When the model produces one or more images (e.g. a project configured for image generation, an image-modification workflow, or a text-to-image prompt), URLs to the generated images are returned in a dedicated field. Image URLs are never inlined as markdown in choices[0].message.content / delta.content.
Non-streaming (stream=false)
The top-level response includes a response.images array. Empty when no images were generated.
{
"id": "chatcmpl-1736541234567",
"object": "chat.completion",
"created": 1736541234,
"model": "default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Here is the rendered image you requested."
},
"finish_reason": "stop"
}
],
"response": {
"images": [
"https://cdn.ainvented.com/generated/abc123.png",
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
]
},
"session_id": "sess_abc123"
}Streaming (stream=true)
Generated images arrive in a dedicated chunk whose choices[0].delta is { images: string[] }. This chunk is interleaved with normal text-delta chunks; one chunk per batch of generated images. The final chunk has finish_reason: "stop" and a top-level session_id, followed by data: [DONE].
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1736541234,"model":"default","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1736541234,"model":"default","choices":[{"index":0,"delta":{"content":"Here is the rendered image you requested."},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1736541234,"model":"default","choices":[{"index":0,"delta":{"images":["https://cdn.ainvented.com/generated/abc123.png"]},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1736541234,"model":"default","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"session_id":"sess_abc123"}
data: [DONE]Content Types
Text Content
{
"type": "'text'",
"text": "string - Text content"
}Image Content (URL or Base64)
{
"type": "'image_url'",
"image_url": {
"url": "string - THREE ACCEPTED FORMS, detected automatically from the value: (1) an http(s) URL, (2) a data URL (data:image/<format>;base64,<data>), or (3) bare base64 with no prefix. Base64 can never begin 'http://' or 'data:' — ':' is outside the base64 alphabet — so the detection is exact, not a guess. Accepted formats: jpeg, png, gif, webp, bmp, tiff, avif — the same set for all three forms. Anything other than jpeg/png is converted losslessly on ingest at its ORIGINAL dimensions, so the same picture costs the same input tokens whichever format you send it in. An http(s) URL is identified from the BYTES it returns, not from its Content-Type header, so a correct image served as 'application/octet-stream' works and an HTML error page served as 'image/png' does not. That download is capped at the same size limit as an inline image and is abandoned as soon as it passes it. A URL must be publicly reachable: private, loopback and cloud-metadata addresses are refused (invalid_url). An unaccepted format or an oversized file is a 400 (unsupported_format / image_too_large) and is never billed; a value that is none of the three forms is a 400 (invalid_image_url); a URL that is simply unreachable is skipped and the rest of the message is answered. BILLING IS IDENTICAL ACROSS THE THREE FORMS — a linked image costs exactly what the same image costs inline. You can also skip this part entirely: a user message whose WHOLE content is one image link is promoted to exactly this part for you (see `messages[].content`).",
"detail": "string (optional) - 'auto' | 'low' | 'high' - Image detail level for token calculation"
}
}Audio Content (URL or Base64)
{
"type": "'input_audio'",
"input_audio": {
"data": "string - THREE ACCEPTED FORMS, detected automatically from the value, exactly as for image_url.url: (1) an http(s) URL to the audio file, (2) a data URL (data:audio/<format>;base64,<data>), or (3) bare base64. A URL is downloaded server-side, capped at the same size limit as inline audio, and identified from the BYTES it returns rather than from its Content-Type, so an HTML error page served as 'audio/mpeg' is refused (unsupported_format) instead of being transcribed and charged to you. A URL must be publicly reachable: private, loopback and cloud-metadata addresses are refused (invalid_url). An oversized file is a 400 (audio_too_large) and is never billed. If the audio was the ONLY content in the message and it could not be retrieved, the request is refused (media_unavailable) rather than answered with an empty prompt you would still be billed for. BILLING IS IDENTICAL ACROSS THE THREE FORMS — a linked clip costs exactly what the same clip costs inline. You can also skip this part entirely: a user message whose WHOLE content is one audio link is promoted to exactly this part for you (see `messages[].content`); a promoted link that cannot be retrieved is left as ordinary text instead of being refused.",
"format": "string - Audio format: 'wav' | 'mp3' | 'm4a' | 'flac' | 'ogg'. REQUIRED with bare base64 (nothing else names the type). OPTIONAL with an http(s) URL or a data URL, which describe themselves — supply it anyway and it is still validated the same way."
}
}Video Content (URL, YouTube or Base64)
{
"type": "'video_url'",
"video_url": {
"url": "string - FOUR ACCEPTED FORMS, detected automatically from the value: (1) an http(s) URL to the video file — downloaded server-side, capped, and identified from its BYTES; (2) a public YouTube link (youtube.com/watch, youtu.be, shorts, live, embed) — read by its address, nothing is downloaded; (3) a data URL (data:video/<format>;base64,<data>); (4) bare base64. Containers: mp4, mov, webm, mkv, 3gp, avi, mpeg, flv, wmv. Up to 50 MB per video and 4 videos per message, 50 MB for all of a message's videos together (configurable); up to the first 20 minutes of a video are read. EVERY MODEL TIER can answer about a video: the platform first turns it into a text record — summary, timestamped visual timeline with all on-screen text, and a verbatim transcript in the spoken language — that the tier you selected reads (a video never moves your request to another tier). BILLING: that record's cost is billed as INPUT tokens of the tier that served the turn, inside the same `usage.prompt_tokens` you already read — no separate line item. A video sent again in a LATER message of the same conversation is NOT parsed or billed again: earlier videos are read from the project's record cache (keep sending your full `messages` history as usual). Errors (400, never billed): invalid_video_url, invalid_url (private address), unsupported_format, video_too_large, too_many_videos, video_unavailable (an explicit link that could not be downloaded, or a YouTube link to a video that does not exist, was removed or is private — the message says which and how to fix it), video_content_rejected (content restrictions). 413 payload_too_large when the request is larger than the platform reads in one request — never billed, do not retry as is. 503 server_busy + Retry-After when too many large requests (over 8 MB — inline videos) are being processed at that moment — retry after the delay; nothing was read or billed. 503 video_processing_unavailable + Retry-After when video reading is momentarily unavailable — retry; nothing is billed. For a public YouTube video that still cannot be read, the same 503 says so: unlisted, age-restricted and members-only videos cannot be read. On a project with `web_search_enabled` = true you can also skip this part entirely: a user message whose WHOLE content is one link to a video file is promoted to exactly this part for you (see `messages[].content`); with it off (the default) such a link stays text."
}
}curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer $AINVENTED_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ainvented-low",
"messages": [{
"role": "user",
"content": [
{ "type": "text", "text": "What happens in this clip? Quote what is said." },
{ "type": "video_url", "video_url": { "url": "https://cdn.example.com/clips/demo.mp4" } }
]
}]
}'
# A public YouTube link works the same way (nothing is downloaded):
# { "type": "video_url", "video_url": { "url": "https://youtu.be/<id>" } }
# Inline: { "type": "video_url", "video_url": { "url": "data:video/mp4;base64,AAAAIGZ0eXBpc29t..." } }URL or Base64 — one rule for both fields
image_url.url and input_audio.data each accept the same three forms, and the form is detected from the value you send — there is no extra parameter to set. Base64 can never begin http:// or data:, so the detection is exact.
{
"model": "ainvented-default",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "Describe the picture, then transcribe the audio." },
// (1) http(s) URL — downloaded server-side, capped, identified by its bytes
{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } },
// (2) data URL — the classic inline form
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." } },
// (3) bare base64 — no prefix, type read from the bytes
{ "type": "image_url", "image_url": { "url": "iVBORw0KGgo..." } },
// Audio takes the same three forms in input_audio.data.
// "format" is OPTIONAL here: the downloaded bytes name the type.
{ "type": "input_audio", "input_audio": { "data": "https://example.com/note.mp3" } },
// "format" is REQUIRED with bare base64 — nothing else names the type.
{ "type": "input_audio", "input_audio": { "data": "UklGRiQ...", "format": "wav" } }
]
}
]
}A message that is only a link
You do not have to build a content part at all. When the entire content of the last user message is a single http(s) link whose path ends in an accepted media extension, it is treated as that file: downloaded, size-capped, identified from its bytes, and attached exactly as if you had written out the image_url / input_audio part yourself. This is what a chat widget, a WhatsApp relay or a bot usually sends when a person shares a photo or a voice note.
# The whole message is the link — no content parts to build.
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ainvented-default",
"messages": [{ "role": "user", "content": "https://example.com/photo.jpg" }]
}'
# Identical to sending it the long way:
# "content": [
# { "type": "image_url",
# "image_url": { "url": "https://example.com/photo.jpg" } }
# ]
# A voice note works the same way:
# "content": "https://example.com/nota.mp3"
# NOT promoted — the link has company, so it keeps its meaning:
# "content": "mira esto https://example.com/photo.jpg" <- text + URL reading
# "content": "https://example.com/a.jpg https://example.com/b.jpg"
# "content": "https://example.com/articulo" <- no media extension
# A link that cannot be used is NOT an error. The message stays the text you
# sent and goes to the model as text, exactly as it does today:
# "content": "https://example.com/borrado.jpg" (404)
# -> the model receives the string "https://example.com/borrado.jpg"
# -> nothing is billed for the file that never arrived
Base64 Image Examples
Python - Image Analysis
Pythonimport requests
import base64
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
# Read and encode image
with open("image.jpg", "rb") as image_file:
image_data = base64.b64encode(image_file.read()).decode('utf-8')
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's in this image?"
},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{image_data}",
"detail": "high"
}
}
]
}
],
"max_tokens": 300
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])TypeScript - Image Analysis
TypeScriptconst apiKey = "your_api_key_here";
const url = "https://ainvented.com/api/v1/chat/completions";
// Read and encode image (Node.js)
import fs from 'fs';
const imageBuffer = fs.readFileSync('image.jpg');
const imageBase64 = imageBuffer.toString('base64');
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
messages: [
{
role: "user",
content: [
{
type: "text",
text: "What's in this image?"
},
{
type: "image_url",
image_url: {
url: `data:image/jpeg;base64,${imageBase64}`,
detail: "high"
}
}
]
}
],
max_tokens: 300
})
});
const result = await response.json();
console.log(result.choices[0].message.content);cURL - Image Analysis
Bash# Portable on macOS and GNU/Linux
IMAGE_BASE64=$(base64 < image.jpg | tr -d '\n')
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"messages\": [
{
\"role\": \"user\",
\"content\": [
{
\"type\": \"text\",
\"text\": \"What's in this image?\"
},
{
\"type\": \"image_url\",
\"image_url\": {
\"url\": \"data:image/jpeg;base64,$IMAGE_BASE64\",
\"detail\": \"high\"
}
}
]
}
],
\"max_tokens\": 300
}"Base64 Audio Examples
Python - Audio Transcription
Pythonimport requests
import base64
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
# Read and encode audio
with open("audio.wav", "rb") as audio_file:
audio_data = base64.b64encode(audio_file.read()).decode('utf-8')
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Transcribe this audio"
},
{
"type": "input_audio",
"input_audio": {
"data": audio_data,
"format": "wav"
}
}
]
}
],
"max_tokens": 500
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])TypeScript - Audio Transcription
TypeScriptconst apiKey = "your_api_key_here";
const url = "https://ainvented.com/api/v1/chat/completions";
// Read and encode audio (Node.js)
import fs from 'fs';
const audioBuffer = fs.readFileSync('audio.wav');
const audioBase64 = audioBuffer.toString('base64');
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Transcribe this audio"
},
{
type: "input_audio",
input_audio: {
data: audioBase64,
format: "wav"
}
}
]
}
],
max_tokens: 500
})
});
const result = await response.json();
console.log(result.choices[0].message.content);cURL - Audio Transcription
Bash# Portable on macOS and GNU/Linux
AUDIO_BASE64=$(base64 < audio.wav | tr -d '\n')
curl https://ainvented.com/api/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"messages\": [
{
\"role\": \"user\",
\"content\": [
{
\"type\": \"text\",
\"text\": \"Transcribe this audio\"
},
{
\"type\": \"input_audio\",
\"input_audio\": {
\"data\": \"$AUDIO_BASE64\",
\"format\": \"wav\"
}
}
]
}
],
\"max_tokens\": 500
}"Browser-Based File Upload
When working in the browser, use the FileReader API to convert files to base64:
JavaScript - Browser File Upload
JavaScript// Browser example — read the file locally, then send it to YOUR server.
// Your server adds the Ainvented API key and forwards the request securely.
const url = "/api/my-agent";
// Handle file input from user
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
const file = e.target.files[0];
// Read file as base64
const reader = new FileReader();
reader.onload = async () => {
// Extract base64 data (remove data URL prefix)
const base64Data = reader.result.split(',')[1];
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
messages: [
{
role: "user",
content: [
{
type: "text",
text: "What's in this image?"
},
{
type: "image_url",
image_url: {
url: `data:image/jpeg;base64,${base64Data}`,
detail: "high"
}
}
]
}
],
max_tokens: 300
})
});
const result = await response.json();
console.log(result.choices[0].message.content);
};
reader.readAsDataURL(file);
});Combined Image and Audio Example
You can send multiple types of content in a single request for rich multimodal interactions:
Python - Combined Image and Audio
Pythonimport requests
import base64
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/chat/completions"
# Read and encode image
with open("chart.png", "rb") as image_file:
image_data = base64.b64encode(image_file.read()).decode('utf-8')
# Read and encode audio
with open("narration.mp3", "rb") as audio_file:
audio_data = base64.b64encode(audio_file.read()).decode('utf-8')
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Analyze this chart and transcribe the audio narration"
},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{image_data}",
"detail": "high"
}
},
{
"type": "input_audio",
"input_audio": {
"data": audio_data,
"format": "mp3"
}
}
]
}
],
"max_tokens": 1000
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])Validation and Error Handling
All multimodal content is validated before processing. The following validations are performed:
- Base64 encoding: Data must contain only valid base64 characters (A-Z, a-z, 0-9, +, /, =)
- Data URL format: Image data URLs must follow the format:
data:image/<format>;base64,<data> - MIME type: Must be a supported image or audio format
- Size limits: Content must not exceed configured size limits (20MB for images, 25MB for audio)
- Required fields: All required fields must be present (e.g., 'data' and 'format' for audio)
Common Validation Errors
Invalid base64 encoding in image data
The base64 string contains invalid characters. Ensure proper encoding.
Malformed data URL: missing MIME type
Data URL must include MIME type: data:image/jpeg;base64,...
Image size (25.3MB) exceeds limit (20MB)
Reduce image size or compress before encoding.
Unsupported image format: svg+xml. Supported formats: jpeg, png, gif, webp, bmp, tiff, avif
Convert image to a supported format. This is a 400 — the request never reaches a model, so it is not billed and retrying the same image will not succeed.
Missing required field 'format' in input_audio
Audio content must include both 'data' and 'format' fields.
Token Estimation for Multimodal Content
Multimodal content consumes tokens based on content type and size:
Image Tokens
- Low detail: Fixed 85 tokens per image
- High detail: 85 + (number of 512px tiles × 170) tokens
- Auto detail: Automatically determined based on image size
Audio Tokens
Estimated based on audio duration: approximately 2 tokens per second of audio. When duration cannot be determined, a conservative estimate is used based on file size.
Best Practices for Multimodal Content
- Optimize file sizes: Compress images and audio before encoding to reduce token usage and improve response times
- Use appropriate detail levels: Use 'low' detail for simple image recognition, 'high' for detailed analysis
- Handle validation errors: Implement proper error handling for validation failures with retry logic
- Monitor size limits: Stay well below size limits (80% threshold triggers warnings)
- Mix content types: Combine text, images, audio and video in a single message for rich interactions
- Backward compatibility: Standard HTTP/HTTPS image URLs continue to work alongside base64 data URLs
Voice
Turn text into natural speech, design a voice from a description or clone one from a recording, and transcribe audio — in more than twenty languages, with catalog voices for English, Spanish, French, German, Italian, Portuguese, Russian, Korean, Japanese, Chinese and Hindi. Calls can run on their own or inside a voice project, which keeps a history you can play, download and list later.
Overview
- Models. Speech:
ainvented-voice(standard — the most natural, follows style directions) andainvented-voice-low(low cost). Transcription:ainvented-transcribe. Clients built for the common speech and transcription APIs work unchanged: their model and voice names are accepted and mapped to these. - Voices. A catalog voice by its id (
olivia,james,lena,chloe,sofia,jiwoo…, seeGET /api/v1/audio/voices), or one of your project's own voices by the id design or cloning returned. Withoutvoice, the text is read by the catalog voice of its own language. Any voice can speak any supported language; setlanguagewhen the text is not in the voice's own language. - Voice projects. Pass
voice_project_idon speech, design or transcription to keep the result in that project's history. Without it the call is billed the same and nothing is kept. - Keys. A project-scoped key works on its own project; an Admin key picks the project with
project_id(or its first project), exactly as chat completions does.
curl https://ainvented.com/api/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"model":"ainvented-voice","voice":"olivia","input":"Hi, thanks for calling.","response_format":"mp3"}' \
--output hello.mp3Languages and voices
The catalog has a female and a male voice for English, Spanish, French, German, Italian, Portuguese, Russian, Korean, Japanese, Chinese and Hindi. Voices that name a region are built from a native speaker of it and keep that regional accent (native_accent: true in the voice list): British English, and Spanish from Mexico, Colombia, Argentina, Chile, Venezuela, the Caribbean and Spain. Speech can be generated in Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish and Turkish; transcription recognizes about a hundred languages and detects the language by itself.
- Any voice reads any language. Without
language, the text is read in the language it is written in (an English sentence for a Spanish voice comes out as English, in that voice); when that is not clear — a single word, say — in the voice's own language. Sendlanguageto decide it yourself. - Another language stays clear. A native-accent, cloned or low-cost catalog voice reading a language other than its own is rendered with
ainvented-voiceon either model, because its accent would otherwise blur the words; it is billed asainvented-voiceand theX-Ainvented-Modelheader says so. - Native-accent voices and voices you cloned have one rendering, the one that keeps the speaker's accent and sounds most like them: both models give the same audio, billed as
ainvented-voice-low(theX-Ainvented-Modelheader says so), andinstructionsare not applied to them (X-Ainvented-Instructions-Applied: false). Designed voices followinstructionsonainvented-voice.
Cost & metering
Speech and voice design are billed per character of text, transcription per second of audio (rounded up), cloning a voice is free (a clone sent without its language has it recognized from the recording, and those few seconds are billed), and catalog samples are free. Each call is charged once, to your project's budget when it has one or to your balance otherwise, and appears in consumption as component voice. A call refused by a budget, quota or balance check costs nothing, and a call that fails costs nothing. Every response reports what it consumed: speech in the X-Ainvented-Usage-Tokens header, the others in usage. These are billing tokens — the call's price expressed in tokens of your standard chat rate, the unit a project's token quota counts — not words or characters, so a short sentence can show a few thousand.
Create speech
Speak `input` and answer the audio file itself (Content-Type per response_format). Billed per character.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"input": "string",
"model": "string",
"voice": "string",
"response_format": "string",
"speed": "number",
"instructions": "string",
"language": "string",
"voice_project_id": "string",
"project_id": "uuid"
}Fields9
inputmodelvoiceresponse_formatspeedinstructionslanguagevoice_project_idproject_idResponse Schema
JSON type shape
{
"body": "the audio bytes",
"X-Request-Id": "header",
"X-Ainvented-Model": "header",
"X-Ainvented-Characters": "header",
"X-Ainvented-Usage-Tokens": "header",
"X-Ainvented-Speed-Applied": "header",
"X-Ainvented-Instructions-Applied": "header",
"X-Ainvented-Generation-Id": "header",
"X-Ainvented-Voice": "header"
}Fields9
bodyX-Request-IdX-Ainvented-ModelX-Ainvented-CharactersX-Ainvented-Usage-TokensX-Ainvented-Speed-AppliedX-Ainvented-Instructions-AppliedX-Ainvented-Generation-IdX-Ainvented-VoiceCode Examples
curl https://ainvented.com/api/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"input":"Your order has shipped.","voice":"olivia","response_format":"wav","speed":1.15,"instructions":"cheerful"}' \
--output order.wavAny client of the common speech API also works: point its base URL at https://ainvented.com/api/v1.
import { writeFile } from 'node:fs/promises'
const res = await fetch('https://ainvented.com/api/v1/audio/speech', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ model: 'ainvented-voice', voice: 'lena', input: 'Guten Morgen und herzlich willkommen.' }),
})
if (!res.ok) throw new Error(await res.text())
await writeFile('guten-morgen.mp3', Buffer.from(await res.arrayBuffer()))Details
Errors
400invalid_model,invalid_input,input_too_long,invalid_language,invalid_speed,invalid_response_format— nothing was billed.404 voice_not_found— the voice id is not in the catalog nor one of this project's voices.402budget_exhausted,token_limit_exhausted,insufficient_balance— refused before any work.409 voice_project_archived— the voice project no longer accepts work.503 voice_unavailable/504 voice_timeout— retry; a failed call is not billed.
Create a transcription
Transcribe an audio file (multipart). Billed per second of audio. The recording is not stored.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"file": "binary",
"model": "string",
"language": "string",
"prompt": "string",
"response_format": "string",
"timestamp_granularities[]": "string",
"voice_project_id": "string",
"project_id": "uuid"
}Fields8
filemodellanguagepromptresponse_formattimestamp_granularities[]voice_project_idproject_idResponse Schema
JSON type shape
{
"text": "string",
"language": "string (verbose_json)",
"duration": "number (verbose_json)",
"segments": "[{ id, start, end, text }] (verbose_json)",
"words": "[{ word, start, end }] (verbose_json with word granularity)",
"usage": "{ type: \"duration\", seconds, total_tokens } (json forms)"
}Fields6
textlanguagedurationsegmentswordsusageCode Examples
curl https://ainvented.com/api/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F file=@interview.mp3 -F response_format=srt
# The language is detected; add -F language=de to set it.List voices
The catalog plus your project's own voices. Filter with ?language=en (or en-GB), ?source=catalog|custom. Free.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"object": "'list'",
"data": "[{ id, object: 'voice', name, description, language, locale (catalog), gender (catalog), style (catalog), source: 'catalog'|'clone'|'design', tiers, preview_available, native_accent (catalog: built from a native speaker, keeps its regional accent) }]",
"languages": "string[]",
"project_id": "uuid"
}Fields4
objectdatalanguagesproject_idCode Examples
curl "https://ainvented.com/api/v1/audio/voices?language=en" -H "Authorization: Bearer $API_KEY"Read a voice
One catalog voice by id, or one of your voices. POST to the same path renames or describes one of your voices ({ name?, description? }); DELETE removes it.
Authentication
Bearer <api_key>
Hear a catalog voice
A short sample of a catalog voice (audio bytes). Free.
Authentication
Bearer <api_key>
Design a voice
A voice from a written description. Answers a billed sample; with save: true the voice is kept and its id works as `voice` in speech.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"description": "string",
"language": "string",
"text": "string",
"save": "boolean",
"name": "string",
"voice_project_id": "string",
"project_id": "uuid"
}Fields7
descriptionlanguagetextsavenamevoice_project_idproject_idResponse Schema
JSON type shape
{
"voice": "Voice | null",
"saved": "boolean",
"save_error": "{ code, message }",
"audio": "{ data: base64, format, mime_type }",
"characters": "number",
"usage": "object",
"generation_id": "string | null"
}Fields7
voicesavedsave_erroraudiocharactersusagegeneration_idCode Examples
curl https://ainvented.com/api/v1/audio/voices/design \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"description":"A woman in her thirties, warm and clear, calm and reassuring","language":"en","save":true,"name":"Claire"}'
# For an authentic regional accent, use a catalog voice from that country (native_accent: true)
# or clone a native speaker: an accent written in the description is only approximate.Clone a voice
Keep a recorded voice as one of your project's voices (multipart). Free when you name the language it speaks. You must have the speaker's permission; delete it at any time.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"file": "binary",
"name": "string",
"consent": "'true'",
"description": "string",
"language": "string",
"voice_project_id": "string",
"project_id": "uuid"
}Fields7
filenameconsentdescriptionlanguagevoice_project_idproject_idResponse Schema
JSON type shape
{
"id": "string",
"object": "'voice'",
"name": "string",
"source": "'clone'",
"language": "string | null",
"created_at": "ISO"
}Fields6
idobjectnamesourcelanguagecreated_atCode Examples
curl https://ainvented.com/api/v1/audio/voices/clone \
-H "Authorization: Bearer $API_KEY" \
-F file=@sam.mp3 -F name="Sam" -F language=en -F consent=true
# Leave language out to have it recognized from the recording (those few seconds are billed).Rename a voice
Rename or describe one of your voices. Catalog voices are read-only (400 voice_read_only).
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"name": "string",
"description": "string | null"
}Fields2
namedescriptionDelete a voice
Deletes one of your voices and its recording. Audio already generated with it stays in your history.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"id": "string",
"object": "'voice'",
"deleted": "true"
}Fields3
idobjectdeletedCreate a voice project
A workspace with its own history and defaults. Free.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"name": "string",
"description": "string",
"default_voice": "string",
"default_model": "'ainvented-voice' | 'ainvented-voice-low'",
"default_language": "string",
"default_format": "'mp3'|'opus'|'aac'|'flac'|'wav'|'pcm'",
"project_id": "uuid"
}Fields7
namedescriptiondefault_voicedefault_modeldefault_languagedefault_formatproject_idResponse Schema
JSON type shape
{
"id": "string",
"object": "'voice_project'",
"name": "string",
"description": "string|null",
"project_id": "uuid",
"status": "'active'|'archived'",
"default_voice": "string|null",
"default_model": "string|null",
"default_language": "string|null",
"default_format": "string|null",
"generation_count": "number",
"created_at": "ISO",
"updated_at": "ISO"
}Fields13
idobjectnamedescriptionproject_idstatusdefault_voicedefault_modeldefault_languagedefault_formatgeneration_countcreated_atupdated_atCode Examples
curl https://ainvented.com/api/v1/voice-projects \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Support line","default_voice":"olivia","default_language":"en"}'List voice projects
?status=active (default)|archived|all, ?limit (≤100), ?cursor, ?order=asc|desc.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"object": "'list'",
"data": "VoiceProject[]",
"next_cursor": "string | null"
}Fields3
objectdatanext_cursorRead a voice project
One voice project, with its generation_count.
Authentication
Bearer <api_key>
Update a voice project
Rename, describe or change its defaults (send null to clear a default). 409 when archived.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"name": "string",
"description": "string|null",
"default_voice": "string|null",
"default_model": "string|null",
"default_language": "string|null",
"default_format": "string|null"
}Fields6
namedescriptiondefault_voicedefault_modeldefault_languagedefault_formatArchive a voice project
Stops new work in it; the history stays readable. Idempotent.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"id": "string",
"object": "'voice_project'",
"status": "'archived'",
"deleted": "true"
}Fields4
idobjectstatusdeletedList a voice project's history
Newest first. ?kind=speech|design|transcription, ?limit, ?cursor.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"object": "'list'",
"data": "[{ id, object: 'voice_generation', kind, input, transcript, voice, model, language, format, units, unit: 'character'|'second', cost_micros, duration_ms, has_audio, audio_url, details, created_at }]",
"next_cursor": "string | null"
}Fields3
objectdatanext_cursorRead a history entry
One entry, including transcript segments. DELETE on the same path removes it and its stored audio (the charge stays on your ledger).
Authentication
Bearer <api_key>
Remove a history entry
Removes the entry and its stored audio.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"id": "string",
"object": "'voice_generation'",
"deleted": "true"
}Fields3
idobjectdeletedDownload generated audio
The stored audio of a speech or design entry, as an attachment named for what it is (project, voice and the first words: anuncio-verano-sofia-este-verano-refrescate.mp3). Free (it was billed when generated).
Authentication
Bearer <api_key>
Execute Workflow
Execute a workflow project programmatically with custom input parameters. The workflow runs using the same logic as the UI, returning results formatted with node labels as keys.
Authentication
Bearer token required in Authorization header. API key must be scoped to a workflow project.
Request Schema
JSON type shape
{
"project_id": "string",
"input_vars": "object",
"images": "string[]",
"audios": "string[]",
"videos": "string[]",
"urls": "string[]",
"url_inputs": "array",
"external_apis": "array",
"model": "string",
"reasoning_effort": "string"
}Fields10
project_idinput_varsimagesaudiosvideosurlsurl_inputsexternal_apismodelreasoning_effortResponse Schema
JSON type shape
{
"success": "boolean",
"output": "object",
"execution_time_ms": "number"
}Fields3
successoutputexecution_time_msCode Examples
Basic workflow execution with input variables and URLs
curl https://ainvented.com/api/v1/workflows/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input_vars": {
"search_query": "AI news",
"max_results": 10
},
"urls": ["https://example.com/feed"]
}'Execute workflow with error handling
import requests
api_key = "your_api_key_here"
url = "https://ainvented.com/api/v1/workflows/execute"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
data = {
"input_vars": {
"search_query": "AI news",
"max_results": 10
},
"urls": ["https://example.com/feed"]
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
if result["success"]:
print("Workflow output:", result["output"])
print(f"Execution time: {result['execution_time_ms']}ms")
else:
print("Error:", result["error"])Execute workflow using fetch API
const apiKey = "your_api_key_here";
const url = "https://ainvented.com/api/v1/workflows/execute";
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
input_vars: {
search_query: "AI news",
max_results: 10
},
urls: ["https://example.com/feed"]
})
});
const result = await response.json();
if (result.success) {
console.log("Workflow output:", result.output);
console.log(`Execution time: ${result.execution_time_ms}ms`);
} else {
console.error("Error:", result.error);
}Type-safe workflow execution
interface WorkflowRequest {
input_vars?: Record<string, any>;
images?: string[];
audios?: string[];
videos?: string[];
urls?: string[];
url_inputs?: Array<{
nodeId: string;
customLabel?: string;
urls: string[];
enabled: boolean;
}>;
external_apis?: Array<{
nodeId?: string;
name: string;
url: string;
method: string;
headers: string;
body: string;
}>;
}
interface WorkflowResponse {
success: boolean;
output: Record<string, any>;
execution_time_ms: number;
}
const apiKey = "your_api_key_here";
const url = "https://ainvented.com/api/v1/workflows/execute";
const request: WorkflowRequest = {
input_vars: {
search_query: "AI news",
max_results: 10
},
urls: ["https://example.com/feed"]
};
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify(request)
});
const result: WorkflowResponse = await response.json();
if (result.success) {
console.log("Workflow output:", result.output);
console.log(`Execution time: ${result.execution_time_ms}ms`);
}Details
Input Parameters
Workflow input parameters match the format used in the UI's "Input Parameters" modal. All parameters are optional, but at least one should be provided:
input_vars: Object with key-value pairs for workflow variablesimages: Array of base64-encoded image stringsaudios: Array of base64-encoded audio stringsvideos: Array of base64-encoded videos (ordata:video/…URLs) for nodes wired to a Video Input node — each is read as a text record and billed as input tokens of the node's tierurls: Array of URL strings for web scraping or data fetching (a link to a video file, or a public YouTube link, is read as a video)url_inputs: Array of URL input objects with node-specific configurationexternal_apis: Array of external API configuration objects — eachurlmust be a public http(s) address; one inside a private network (or resolving or redirecting there) is refused with400 invalid_url
Choosing a model
A workflow is not one kind of work. “Pull the invoice number out of this PDF” and “write the customer's reply” have different value and different cost, so each node in a workflow can run on its own model tier and its own reasoning effort, set in the functions‑workflow‑builder.
The optional model and reasoning_effort fields set the default for this run. They move every node whose author left it on the default and leave explicitly pinned nodes alone — so passing "model": "low"makes the cheap steps cheaper without quietly downgrading the one step the workflow exists for.
- Precedence, highest first: the node's own pin → this request → the workflow default → the project default →
ainvented-default. - Accepted models:
ainvented-epic,ainvented-saga,ainvented-default(alsoainvented-lite/lite),ainvented-low. The bare wordsepic,saga,lowwork too. - Accepted efforts:
low,medium,high,xhigh,max. Reasoning tokens are billed as output tokens, so a higher effort costs more. - An unrecognised value returns
400. An empty string means “not selected” and is accepted. - A node that sends images is always served on the vision-capable standard model and billed at that rate, whatever tier was requested.
- A tier this deployment has not enabled is served — and billed — as the standard tier.
GET /v1/modelslists what is available to you.
Output Format
The workflow output is formatted with node labels as keys, matching the format displayed in the UI toaster. Each node's output is accessible by its label:
Workflows may include Files and Multimodal RAG context nodes (configured in the functions‑workflow‑builder). They enrich downstream nodes with file URLs or vector‑store search results and are billed to your project as audited usage. They are internal to the workflow and do not change this endpoint's request or response contract.
{
"success": true,
"output": {
"Web Scraper": {
"articles": [
{"title": "AI Breakthrough", "url": "..."},
{"title": "ML Advances", "url": "..."}
]
},
"Summarizer": {
"summary": "Recent AI developments include..."
}
},
"execution_time_ms": 2341
}Project Selection
The API determines which workflow project to execute based on this priority order:
- API key's associated project (if configured) - Takes precedence over all other options
project_idparameter (if API key is not scoped to a project)- Your default project (first created workflow project)
Rate Limiting
Workflow execution uses the same rate limiting as the chat completions endpoint. Rate limit headers are included in all responses:
X-RateLimit-Limit: Maximum requests per time windowX-RateLimit-Remaining: Requests remaining in current windowX-RateLimit-Reset: Unix timestamp when limit resets
Error Responses
Workflow execution can return the following error codes:
{
"error": {
"message": "string - Human-readable error message",
"type": "string - Error type (authentication_error, permission_denied, validation_error, etc.)",
"code": "string - Specific error code"
}
}- 401 Unauthorized: Invalid, missing, or revoked API key
- 403 Forbidden: Project doesn't belong to your account or is disabled
- 404 Not Found: Workflow project doesn't exist
- 422 Validation Error: Invalid input parameters or malformed JSON
- 429 Too Many Requests: Rate limit exceeded
- 500 Server Error: Workflow execution failed or internal error
Example Success Response
{
"success": true,
"output": {
"Web Scraper": {
"articles": [
{"title": "AI Breakthrough", "url": "https://example.com/article1"},
{"title": "ML Advances", "url": "https://example.com/article2"}
]
},
"Summarizer": {
"summary": "Recent AI developments include breakthrough in neural networks..."
}
},
"execution_time_ms": 2341
}Example Error Response
{
"error": {
"message": "Invalid API key. Please check your API key and try again.",
"type": "invalid_request_error",
"code": "authentication_error"
}
}Projects
Manage chat projects with their assigned API keys, two independent quotas (cents-budget and token-units quota), currency, alert thresholds, and hard-cap policies. Every monetized AI call routes through both quotas — when hard_cap is true and consumed >= budget, the gate refuses with 402 insufficient_balance; when token_hard_capis true and projected token usage would exceed token_limit, the gate refuses with 402 insufficient_token_quota— both checks happen before any billable work begins, so over-budget requests are never charged. The token check runs first; the response code lets clients tell the two refusals apart.
export BASE="https://ainvented.com"
export API_KEY="your_admin_api_key"
export PID="your_project_id"
# The account-wide bulk endpoints below refuse a project-scoped key with 403, so their
# examples name the variable ADMIN_KEY to make that requirement obvious. Same value.
export ADMIN_KEY="$API_KEY"Create chat project
Creates a chat project, its initial API key, and its initial budget in a single transaction. The full API key is returned ONCE; subsequent reads expose only the partial key.
Authentication
Bearer <api_key> — must be an Admin key (no project binding). See the Authentication section above for the scope rules.
Request Schema
JSON type shape
{
"name": "string",
"type": "\"chat\" | \"function\" | \"canvas\"",
"budget_cents": "integer cents",
"currency": "\"USD\" | \"EUR\" | \"GBP\" | \"CAD\" | \"AUD\"",
"alert_thresholds": "integer[]",
"hard_cap": "boolean",
"token_limit": "integer",
"token_hard_cap": "boolean",
"web_search_enabled": "boolean",
"prompt_cache_enabled": "boolean",
"prompt_cache_ttl_hours": "string|integer|null",
"preconfigured_model": "'ainvented-default' | 'ainvented-low' | 'ainvented-saga' | 'ainvented-epic'",
"preconfigured_effort": "'low' | 'medium' | 'high' | 'xhigh' | 'max'"
}Fields13
nametypebudget_centscurrencyalert_thresholdshard_captoken_limittoken_hard_capweb_search_enabledprompt_cache_enabledprompt_cache_ttl_hourspreconfigured_modelpreconfigured_effortResponse Schema
JSON type shape
{
"id": "uuid",
"name": "string",
"type": "integer",
"type_name": "\"chat\" | \"function\" | \"canvas\"",
"api_key": {
"id": "uuid",
"key": "full key",
"partialKey": "last 4 chars"
},
"budget": {
"budget_cents": "number",
"consumed_cents": "number",
"remaining_cents": "number",
"remaining_pct": "number",
"currency": "string",
"hard_cap": "boolean",
"alert_thresholds": "number[]",
"fired_thresholds": "number[]",
"token_limit": "number",
"consumed_tokens": "number",
"remaining_tokens": "number",
"remaining_tokens_pct": "number",
"token_hard_cap": "boolean",
"fired_token_thresholds": "number[]"
},
"web_search_enabled": "boolean",
"prompt_cache_enabled": "boolean",
"prompt_cache_ttl_hours": "string|integer|null",
"preconfigured_model": "string",
"preconfigured_effort": "string|null",
"created_at": "ISO timestamp"
}Fields29
idnametypetype_nameapi_keyidkeypartialKeybudgetbudget_centsconsumed_centsremaining_centsremaining_pctcurrencyhard_capalert_thresholdsfired_thresholdstoken_limitconsumed_tokensremaining_tokensremaining_tokens_pcttoken_hard_capfired_token_thresholdsweb_search_enabledprompt_cache_enabledprompt_cache_ttl_hourspreconfigured_modelpreconfigured_effortcreated_atCode Examples
Create a chat project with a $250 budget AND a 1 000 000-token hard cap. Using the canonical string for `type`.
curl -X POST $BASE/api/v1/projects \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "qa-prod-1",
"type": "chat",
"budget_cents": 25000,
"currency": "USD",
"alert_thresholds": [50, 80, 95, 100],
"hard_cap": true,
"token_limit": 1000000,
"token_hard_cap": true
}'Submitting an unsupported value returns a structured error listing the allowed values.
curl -X POST $BASE/api/v1/projects \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "x", "type": "pigeon"}'
# Response — 400 Bad Request
# {
# "error": {
# "message": "Invalid project type. Allowed string values: \"chat\", \"function\", \"canvas\"; legacy integer values: 1, 2, 3.",
# "type": "invalid_request_error",
# "param": "type"
# }
# }List projects for the authenticated user
Returns the projects owned by the API key's user, with a budget summary per row. Without query parameters it returns every non-deleted project, newest first (the original behaviour, unchanged). Add any of the query parameters below to switch to the PAGED mode — sorted and filtered on the server, one page at a time — which is what the Partner Console's projects table uses and what an account with thousands of projects should use.
Authentication
Bearer <api_key> — must be an Admin key (no project binding).
Request Schema
JSON type shape
{
"limit": "integer 1..200 (query, optional; default 50)",
"offset": "integer >= 0 (query, optional; default 0)",
"sort": "\"name\" | \"created_at\" | \"expiration_date\" | \"consumed_cents\" | \"budget_cents\" | \"remaining_cents\" | \"consumed_tokens\" (query, optional; default \"created_at\")",
"dir": "\"asc\" | \"desc\" (query, optional)",
"q": "string, max 80 (query, optional)",
"status": "\"active\" | \"disabled\" | \"all\" (query, optional; default \"active\")"
}Fields6
limitoffsetsortdirqstatusResponse Schema
JSON type shape
{
"data": [
{
"id": "uuid",
"name": "string",
"type": "integer",
"type_name": "\"chat\" | \"function\" | \"canvas\"",
"disabled": "boolean",
"created_at": "ISO",
"expiration_date": "ISO",
"prompt_cache_ttl_hours": "string|integer|null",
"budget": {
"budget_cents": "number",
"consumed_cents": "number",
"currency": "string",
"hard_cap": "boolean",
"token_limit": "number",
"consumed_tokens": "number",
"remaining_tokens": "number",
"remaining_tokens_pct": "number",
"token_hard_cap": "boolean"
}
}
],
"page": "{ limit, offset, total, has_more }",
"sort": "{ key, dir }",
"filters": "{ q: string|null, status }"
}Fields22
dataidnametypetype_namedisabledcreated_atexpiration_dateprompt_cache_ttl_hoursbudgetbudget_centsconsumed_centscurrencyhard_captoken_limitconsumed_tokensremaining_tokensremaining_tokens_pcttoken_hard_cappagesortfiltersCode Examples
curl $BASE/api/v1/projects -H "Authorization: Bearer $API_KEY"The second page of 50, the most-consumed first, only projects whose name contains "shop".
curl "$BASE/api/v1/projects?limit=50&offset=50&sort=consumed_cents&dir=desc&q=shop&status=active" \
-H "Authorization: Bearer $API_KEY"
# {
# "data": [ { "id": "…", "name": "shop-eu", "expiration_date": "…", "budget": { … } }, … ],
# "page": { "limit": 50, "offset": 50, "total": 1284, "has_more": true },
# "sort": { "key": "consumed_cents", "dir": "desc" },
# "filters": { "q": "shop", "status": "active" }
# }Bulk: set the managed-cache value on all (or selected) projects
Batch-applies one Managed Prompt Cache value to every project of your account — or to a chosen subset — in a single call, the API twin of the partner console's 'apply to all projects' button. Accepts a fixed TTL, 'auto' (hand every project to the optimizer), or null (off). Projects without a settings row get one created. Safe at any scale: a project whose prompts are never reused mints no cache and pays no storage (creation requires the prefix to be seen 3 times within 10 minutes). Audit log emits one project.prompt_cache_ttl.set row per project whose value actually changed.
Authentication
Bearer <api_key> — must be an Admin key (no project binding).
Request Schema
JSON type shape
{
"prompt_cache_ttl_hours": "string|integer|null",
"project_ids": "array"
}Fields2
prompt_cache_ttl_hoursproject_idsResponse Schema
JSON type shape
{
"updated": "integer",
"prompt_cache_ttl_hours": "string|integer|null"
}Fields2
updatedprompt_cache_ttl_hoursCode Examples
curl -X PUT $BASE/api/v1/projects/cache-ttl \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt_cache_ttl_hours": "auto"}'curl -X PUT $BASE/api/v1/projects/cache-ttl \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt_cache_ttl_hours": 6, "project_ids": ["<uuid-1>", "<uuid-2>"]}'Bulk: set the default model and reasoning effort on all (or selected) projects
Batch-applies a default model and/or a default reasoning effort to every project of your account — or to a chosen subset — in a single call, instead of one PUT per project. Both fields are the values used when a request omits `model` / `reasoning_effort`; a request that names either is unaffected. Send at least one of the two (an empty patch returns 400). Projects without a settings row get one created. BILLING: the default model decides which tier's input, cached-input and output rate an unnamed-model request is billed at, and a higher default effort spends more output tokens per turn — on a request that sets its own max_tokens, that cap bounds the visible answer only and thinking tokens are billed on top of it. Channel (connector) messages, scheduled tasks, evaluation judges that name no tier of their own, vector-store answers and the builder's AI helpers cannot name a model or an effort per request, so BOTH defaults apply to them: they are served on the project's default tier at the project's default effort and billed at that tier's rates. A workflow follows its own selection first (a node's pin, then the workflow default) and falls back to the project default. Pinning a premium tier therefore changes what serves every turn of the project, not only its price. Audit log emits one project.preconfigured_model.set and/or project.preconfigured_effort.set row per project whose stored value actually changed, so every repricing stays attributable to the account that made it; re-applying a value a project already holds writes no row.
Authentication
Bearer <api_key> — must be an Admin key (no project binding).
Request Schema
JSON type shape
{
"preconfigured_model": "string",
"preconfigured_effort": "string|null",
"project_ids": "array"
}Fields3
preconfigured_modelpreconfigured_effortproject_idsResponse Schema
JSON type shape
{
"updated": "integer",
"preconfigured_model": "string",
"preconfigured_effort": "string|null"
}Fields3
updatedpreconfigured_modelpreconfigured_effortCode Examples
curl -X PUT $BASE/api/v1/projects/defaults \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"preconfigured_model": "ainvented-low", "preconfigured_effort": "medium"}'curl -X PUT $BASE/api/v1/projects/defaults \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"preconfigured_effort": null, "project_ids": ["<uuid-1>", "<uuid-2>"]}'Read a project (with counts)
Returns the project, its full budget snapshot, and component counts (connectors, skills, workflows). A deleted project returns 404.
Authentication
Bearer <api_key> — must own the project.
Response Schema
JSON type shape
{
"id": "uuid",
"name": "string",
"type": "integer",
"type_name": "\"chat\" | \"function\" | \"canvas\"",
"disabled": "boolean",
"created_at": "ISO",
"budget": "BudgetSnapshot",
"preconfigured_model": "string",
"default_model": "string",
"web_search_enabled": "boolean",
"prompt_cache_enabled": "boolean",
"prompt_cache_ttl_hours": "string|integer|null",
"preconfigured_effort": "string|null",
"counts": {
"connector": "number",
"skill": "number",
"workflow": "number"
}
}Fields17
idnametypetype_namedisabledcreated_atbudgetpreconfigured_modeldefault_modelweb_search_enabledprompt_cache_enabledprompt_cache_ttl_hourspreconfigured_effortcountsconnectorskillworkflowCode Examples
curl $BASE/api/v1/projects/$PID -H "Authorization: Bearer $API_KEY"Update a project
Patches name, budget_cents, currency, alert_thresholds, hard_cap, disabled, token_limit, token_hard_cap, web_search_enabled, prompt_cache_enabled, prompt_cache_ttl_hours, and preconfigured_effort. Currency cannot be changed once consumed_cents > 0 (returns 409). Managed cache is a single unified selector: setting prompt_cache_ttl_hours to 'auto' hands the lifetime to the optimizer; a number/null sets a fixed TTL and turns auto off — there is no separate flag and no manual/auto interlock. Updating alert_thresholds re-arms BOTH fired_thresholds and fired_token_thresholds; updating token_limit re-arms fired_token_thresholds. Lowering token_limit below current consumed_tokens is allowed and is not retroactive — the next request is evaluated against the new limit. Empty patch returns 400. Audit log emits project.token_limit.set and project.token_limit.cap_toggle, project.web_search.toggle, project.prompt_caching.toggle, project.prompt_cache_ttl.set, and project.preconfigured_effort.set, when the corresponding fields change.
Authentication
Bearer <api_key> — must own the project.
Request Schema
JSON type shape
{
"name": "string",
"budget_cents": "integer",
"currency": "\"USD\" | \"EUR\" | \"GBP\" | \"CAD\" | \"AUD\"",
"alert_thresholds": "integer[]",
"hard_cap": "boolean",
"disabled": "boolean",
"token_limit": "integer",
"token_hard_cap": "boolean",
"web_search_enabled": "boolean",
"prompt_cache_enabled": "boolean",
"prompt_cache_ttl_hours": "string|integer|null",
"preconfigured_model": "'ainvented-default' | 'ainvented-low' | 'ainvented-saga' | 'ainvented-epic'",
"preconfigured_effort": "'low' | 'medium' | 'high' | 'xhigh' | 'max' | null"
}Fields13
namebudget_centscurrencyalert_thresholdshard_capdisabledtoken_limittoken_hard_capweb_search_enabledprompt_cache_enabledprompt_cache_ttl_hourspreconfigured_modelpreconfigured_effortResponse Schema
JSON type shape
{
"id": "uuid",
"name": "string",
"disabled": "boolean",
"budget": "BudgetSnapshot (includes token fields)",
"web_search_enabled": "boolean",
"prompt_cache_enabled": "boolean",
"prompt_cache_ttl_hours": "string|integer|null",
"preconfigured_model": "string",
"preconfigured_effort": "string|null"
}Fields9
idnamedisabledbudgetweb_search_enabledprompt_cache_enabledprompt_cache_ttl_hourspreconfigured_modelpreconfigured_effortCode Examples
Raise budget, tighten alerts, and switch to a 500 000-token hard cap.
curl -X PUT $BASE/api/v1/projects/$PID \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"budget_cents": 50000,
"alert_thresholds": [25, 50, 75, 100],
"token_limit": 500000,
"token_hard_cap": true
}'Delete a project
Deletes the project, revokes all of its API keys and deactivates all of its webhooks. Idempotent: a second call returns 410. Subsequent reads return 404.
Authentication
Bearer <api_key> — must own the project.
Code Examples
curl -X DELETE $BASE/api/v1/projects/$PID -H "Authorization: Bearer $API_KEY"Payments
Collect payments from your end-clients into ainvented's Stripe account. By default the equivalent USD amount is credited to your user balance; optionally set credit_target: "project_budget"to credit a project budget instead. USD only. Refunds happen via the Stripe dashboard and are mirrored read-only — they never debit your balance. You can also configure per-project auto-recharge(below) to top a project budget up automatically when it runs low.
Create a payment
Creates a Stripe PaymentIntent on ainvented's Stripe account and returns a client_secret your frontend uses with Stripe.js. Amount is the smallest USD unit (cents) and must be between 50 ($0.50, Stripe's USD floor) and 99,999,999 ($999,999.99). EASIEST INTEGRATION: pass hosted_checkout:true to get a checkout_url instead — redirect your customer to it and you need NO Stripe key at all (not even the publishable key). For amounts ≥ $10, that checkout_url is OUR customer checkout page, which also collects the customer's email (Stripe emails them a receipt for this payment and for every later auto-reload charge), lets them set up auto-reload (toggle ON by default, they can opt out) and return to your site after paying — you don't have to send anything extra. See hosted_checkout + auto_reload below.
Authentication
Bearer <admin_api_key> — must be an account-wide Admin key, must own the project, and your account must be approved for payment collection.
Request Schema
JSON type shape
{
"amount_cents": "integer",
"currency": "\"USD\" (literal; any other value → 400)",
"description": "string",
"idempotency_key": "string",
"credit_target": "\"user_balance\" | \"project_budget\" . Embedded and under-$10 hosted flows default to \"user_balance\". For backward compatibility, the AInvented-hosted $10+ checkout defaults to this path project's \"project_budget\". An explicit value is always honored.",
"budget_project_id": "uuid",
"hosted_checkout": "boolean . true → response returns a checkout_url; redirect your customer there. You need NO Stripe key, not even the publishable key. BY DEFAULT (amount_cents ≥ $10) this returns OUR customer checkout page with a required email field (so Stripe receipts the payment and every later auto-reload charge) and an opt-out auto-reload toggle, so your customers can set up auto-reload without you sending anything. success_url/cancel_url are honored on that page as a \"Return to site\" button + a back link (they no longer force the plain Stripe page). The only case that stays on the plain Stripe-hosted page is amount_cents < $10 (too small to carry auto-reload). To keep our page but start the toggle OFF (opt-in), send auto_reload:{enabled:false}; to customize the default amounts, send your own auto_reload object.",
"success_url": "url",
"cancel_url": "url",
"auto_reload": "object"
}Fields10
amount_centscurrencydescriptionidempotency_keycredit_targetbudget_project_idhosted_checkoutsuccess_urlcancel_urlauto_reloadResponse Schema
JSON type shape
{
"payment_id": "uuid",
"stripe_client_secret": "pi_*_secret_*",
"checkout_url": "the page to redirect the customer to (hosted_checkout=true only). For amounts ≥ $10 this is OUR checkout page",
"checkout_session_id": "cs_*",
"stripe_payment_intent_id": "pi_*",
"status": "PaymentStatus enum (REQUIRES_PAYMENT_METHOD, PROCESSING, SUCCEEDED, ...)",
"amount_cents": "integer",
"currency": "\"USD\"",
"description": "string | null",
"credit_target": "\"user_balance\" | \"project_budget\"",
"credited_budget_project_id": "uuid | null",
"created_at": "ISO timestamp",
"idempotent_replay": "boolean",
"auto_reload": "object | absent"
}Fields14
payment_idstripe_client_secretcheckout_urlcheckout_session_idstripe_payment_intent_idstatusamount_centscurrencydescriptioncredit_targetcredited_budget_project_idcreated_atidempotent_replayauto_reloadCode Examples
Easiest integration: get a checkout_url and redirect your customer. For $10+ they land on OUR checkout page — enter an email (Stripe receipts every charge to it), pay + (by default) opt into auto-reload — then a "Return to site" button sends them to success_url. You send nothing extra; you never touch Stripe.
curl -X POST $BASE/api/v1/projects/$PID/payments \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 5000,
"currency": "USD",
"credit_target": "project_budget",
"hosted_checkout": true,
"success_url": "https://your-app.com/thanks",
"cancel_url": "https://your-app.com/cart"
}'
# → { "payment_id": "...",
# "checkout_url": "https://ainvented.com/checkout/<token>", # OUR page (amount ≥ $10)
# "auto_reload": { "applied": false, "pending": true,
# "defaults": { "enabled": true, "threshold_cents": 1000, "recharge_cents": 2000 } }, ... }
# Redirect your customer to checkout_url. No publishable key, no Stripe.js.
# (Want the toggle OFF by default? add "auto_reload": {"enabled": false}.
# Amounts under $10 return a plain Stripe checkout_url with no auto-reload.)Create a $50.00 payment, then your frontend redeems the client_secret with Stripe.js Elements + your publishable key.
curl -X POST $BASE/api/v1/projects/$PID/payments \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 5000,
"currency": "USD",
"description": "Order #12345 — Acme Co.",
"idempotency_key": "order-12345"
}'When your account is not yet approved for payment collection.
# Response — 403 Forbidden
# {
# "error": {
# "message": "This account is not approved for payment collection. Contact ainvented at contact@ainvented.com to request access to the payments endpoints.",
# "type": "permission_error",
# "code": "payments_not_enabled"
# }
# }
#
# To request access, email contact@ainvented.com with:
# - your ainvented user id
# - a brief description of your business
# - the project id you want to charge from# Response — 400 Bad Request
# {
# "error": {
# "message": "Invalid literal value, expected \"USD\"",
# "type": "invalid_request_error",
# "param": "currency"
# }
# }The same idempotency_key was used for a different flow, amount, description, credit destination, hosted URL, or auto-reload choice. Mint a fresh key for a new payment, or resend the original request to receive it as a replay.
# Response — 400 Bad Request
# {
# "error": {
# "message": "idempotency_key was used for a different payment request. Use a fresh key or resend the original request.",
# "type": "invalid_request_error",
# "param": "idempotency_key",
# "code": "idempotency_key_reused"
# }
# }The project was deleted, so it cannot take new payments.
# Response — 403 Forbidden
# {
# "error": {
# "message": "Project is disabled",
# "type": "permission_error",
# "code": "project_disabled"
# }
# }Stripe was unreachable, returned a 5xx, or rejected the request. Safe to retry with the same idempotency_key.
# Response — 502 Bad Gateway
# {
# "error": {
# "message": "Payment provider error — please retry",
# "type": "payment_provider_error"
# }
# }Your frontend mounts Stripe Elements with the client_secret + ainvented's publishable key. No Stripe secret key is ever in the browser.
const stripe = Stripe('pk_live_AINVENTED_PUBLISHABLE_KEY');
const elements = stripe.elements({ clientSecret });
elements.create('payment').mount('#payment-element');
document.querySelector('#submit').addEventListener('click', async () => {
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: 'https://your-site.com/return' },
redirect: 'if_required',
});
if (error) console.error(error.message);
});List payments for a project
Returns payments ordered by created_at DESC. Supports pagination + status / date filters.
Authentication
Bearer <api_key> — must own the project AND your account must be approved for payment collection.
Request Schema
JSON type shape
{
"query.status": "optional PaymentStatus enum (REQUIRES_PAYMENT_METHOD|PROCESSING|REQUIRES_ACTION|SUCCEEDED|FAILED|CANCELED|REFUNDED)",
"query.limit": "integer 1..200 (default 20)",
"query.offset": "integer ≥ 0 (default 0)",
"query.from": "ISO timestamp (inclusive)",
"query.to": "ISO timestamp (exclusive)"
}Fields5
query.statusquery.limitquery.offsetquery.fromquery.toResponse Schema
JSON type shape
{
"data": [
{
"payment_id": "uuid",
"amount_cents": "integer",
"amount_received_cents": "integer (0 until succeeded)",
"currency": "\"USD\"",
"status": "PaymentStatus enum",
"description": "string | null",
"credit_target": "\"user_balance\" | \"project_budget\"",
"credited_budget_project_id": "uuid | null",
"stripe_payment_intent_id": "string",
"error_code": "string | null",
"error_message": "string | null",
"created_at": "ISO",
"paid_at": "ISO | null",
"refunded_at": "ISO | null"
}
],
"page": {
"limit": "integer",
"offset": "integer",
"has_more": "boolean"
}
}Fields19
datapayment_idamount_centsamount_received_centscurrencystatusdescriptioncredit_targetcredited_budget_project_idstripe_payment_intent_iderror_codeerror_messagecreated_atpaid_atrefunded_atpagelimitoffsethas_moreCode Examples
curl "$BASE/api/v1/projects/$PID/payments?status=SUCCEEDED&limit=50" -H "Authorization: Bearer $API_KEY"Read a single payment
Returns the full payment shape. Returns 404 if the payment is not in this project (cross-project lookups are not allowed).
Authentication
Bearer <api_key> — must own the project AND your account must be approved for payment collection.
Response Schema
JSON type shape
{
"payment_id": "uuid",
"project_id": "uuid",
"amount_cents": "integer",
"amount_received_cents": "integer",
"currency": "\"USD\"",
"status": "PaymentStatus enum",
"description": "string | null",
"stripe_payment_intent_id": "string",
"error_code": "string | null",
"error_message": "string | null",
"created_at": "ISO",
"paid_at": "ISO | null",
"refunded_at": "ISO | null"
}Fields13
payment_idproject_idamount_centsamount_received_centscurrencystatusdescriptionstripe_payment_intent_iderror_codeerror_messagecreated_atpaid_atrefunded_atCode Examples
curl "$BASE/api/v1/projects/$PID/payments/$PMT_ID" -H "Authorization: Bearer $API_KEY"Save a card (SetupIntent or hosted checkout)
Starts the save-card flow so a card can later back project auto-recharge. Default (embedded): ainvented creates a Stripe customer + SetupIntent server-side and returns a client_secret you confirm with Stripe.js + the PUBLIC publishable key. EASIEST: pass hosted_checkout:true to get a Stripe-hosted checkout_url (setup-mode) — redirect your customer there and you need NO Stripe key at all. Either way the saved pm_… attaches to your customer and is reusable across all your projects. You never touch ainvented's Stripe secret key.
Authentication
Bearer <api_key> — must own the project AND your account must be approved for payment collection.
Request Schema
JSON type shape
{
"hosted_checkout": "boolean . true → returns a Stripe-hosted checkout_url (no client_secret, no publishable key needed).",
"success_url": "url",
"cancel_url": "url"
}Fields3
hosted_checkoutsuccess_urlcancel_urlResponse Schema
JSON type shape
{
"client_secret": "string",
"checkout_url": "https://checkout.stripe.com/…",
"customer_id": "string",
"publishable_key": "string | null"
}Fields4
client_secretcheckout_urlcustomer_idpublishable_keyCode Examples
Redirect your customer to checkout_url to save a card; it then backs per-project auto-recharge.
curl -X POST "$BASE/api/v1/projects/$PID/payment-methods" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"hosted_checkout": true, "success_url": "https://your-app.com/card-saved"}'
# → { "data": { "checkout_url": "https://checkout.stripe.com/c/pay/cs_...", "customer_id": "cus_..." } }curl -X POST "$BASE/api/v1/projects/$PID/payment-methods" -H "Authorization: Bearer $API_KEY"List saved cards
Returns the cards saved on your ainvented Stripe customer (so you can pick a pm_… for auto-recharge). Returns [] if you have not saved a card yet.
Authentication
Bearer <api_key> — must own the project AND be approved for payment collection.
Response Schema
JSON type shape
{
"id": "string (pm_…)",
"brand": "string | null",
"last4": "string | null",
"exp_month": "integer | null",
"exp_year": "integer | null"
}Fields5
idbrandlast4exp_monthexp_yearCode Examples
curl "$BASE/api/v1/projects/$PID/payment-methods" -H "Authorization: Bearer $API_KEY"Project auto-reload (create / get / update / disable)
Configure automatic top-up (auto-reload) of a PROJECT BUDGET. When the project’s remaining budget (budget_cents − consumed_cents) drops below threshold_cents, ainvented charges your saved card off-session for recharge_cents and credits the project budget. Four verbs: POST create/enable/partial-patch (enabled required; money/card fields merge onto any existing config; 201 new, 200 update); PUT upsert (full OR partial; money fields optional and merged; 200); GET returns the config (or null); DELETE turns it off (active=false). A lightweight toggle is just a POST with enabled=false or enabled=true. The payment_method_id (pm_…) must already be saved via POST /payment-methods. recharge_cents must be ≥ threshold_cents, and enabling requires a saved card. Each recharge is recorded as a project payment (credit_target=project_budget), is charge-idempotent per 60s window, and fires no AI call.
Authentication
Bearer <admin api_key> — must own the project AND be approved for payment collection. (Admin key required; project-scoped keys get 403 admin_key_required.)
Request Schema
JSON type shape
{
"enabled": "boolean (POST: required",
"threshold_cents": "integer",
"recharge_cents": "integer (optional*, 1000..99,999,999",
"payment_method_id": "string"
}Fields4
enabledthreshold_centsrecharge_centspayment_method_idResponse Schema
JSON type shape
{
"project_id": "uuid",
"threshold_cents": "integer",
"recharge_cents": "integer",
"active": "boolean",
"payment_method_id": "string | null",
"last_triggered_at": "ISO | null",
"updated_at": "ISO | null"
}Fields7
project_idthreshold_centsrecharge_centsactivepayment_method_idlast_triggered_atupdated_atCode Examples
curl -X POST "$BASE/api/v1/projects/$PID/auto-recharge" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"enabled": true, "threshold_cents": 1000, "recharge_cents": 5000, "payment_method_id": "pm_..."}'curl -X POST "$BASE/api/v1/projects/$PID/auto-recharge" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"enabled": false}'curl "$BASE/api/v1/projects/$PID/auto-recharge" -H "Authorization: Bearer $API_KEY"
curl -X DELETE "$BASE/api/v1/projects/$PID/auto-recharge" -H "Authorization: Bearer $API_KEY"Webhook events
Subscribe via POST /api/v1/projects/{id}/webhooks with events: ['payment.succeeded', 'payment.failed'] in the body.
payment.succeeded— fired once when the PaymentIntent reaches the terminal succeeded state. Payload includesamount_received_cents,paid_at,stripe_payment_intent_id.payment.failed— fired on each failed attempt (Stripe allows retries). Payload includeserror_code,error_message.
No DELETE endpoint. Refunds are not supported via API. If you need to refund a customer, use the Stripe dashboard; the row's status will mirror to REFUNDED but your balance is NOT debited (manual reconciliation).
Attach a customer's own WhatsApp Business account to one of your projects. You call one endpoint, get back a URL, and hand it to your customer — they sign in with Meta and pick their number. Neither you nor they ever type a WhatsApp access token, a phone number ID or a verify token; Ainvented obtains them from Meta server-side and stores them encrypted.
Once connected, a WhatsApp account appears on the project. What happens to the messages it receives depends on the account's mode, chosen when you mint the link: either the project's assistant answers by itself, or — the default for links minted through this API — every message is handed to your application through a webhook and you reply through the API, with nothing generated in between. All of these endpoints are reserved for reseller accounts and take an Admin API key.
Assistant mode vs API mode
mode: "assistant" | mode: "api" (default here) | |
|---|---|---|
| Who answers | The project's assistant, immediately, from the customer's number. Same behaviour as connecting from the AI Chat view. | Your application. Nothing is generated: the message is stored, delivered to your webhooks, and you reply — or not — with POST /whatsapp/messages. |
| What it costs you | Each inbound message is a priced assistant turn on the project, like a chat completion. | No tokens are spent on the project for inbound or outbound messages. WhatsApp bills the customer's own account for conversations, as always. |
| History | Lives with the chat session; not exposed here. | GET /whatsapp/conversations and GET /whatsapp/messages hold every message in both directions, including failed sends. |
| Switching | Any time, without reconnecting: PUT /whatsapp/accounts/{accountId} with the new mode. Accounts connected before modes existed are assistants until you switch them. | |
Create a connect link
Mints a one-shot URL that walks your customer through Meta's Embedded Signup and attaches the resulting WhatsApp Business account to this project. Same shape as hosted checkout: you get a URL and hand it over — no SDK, no Meta app of your own. The link is single-use and expires after 7 days. The account it creates is in API mode unless you ask for an assistant. Send the customer's number with it: the link then finishes even if they close our page early, and they are never asked for it.
Authentication
Bearer <admin_api_key> — must be an account-wide Admin key (no project binding), must own the project, and the account must be a reseller.
Request Schema
JSON type shape
{
"connector_name": "string",
"return_url": "url",
"mode": "\"api\" | \"assistant\" (optional, default \"assistant\"",
"phone_number": "string"
}Fields4
connector_namereturn_urlmodephone_numberResponse Schema
JSON type shape
{
"connect_url": "the URL to hand your customer",
"connect_token": "the token embedded in that URL; use it to correlate with the list endpoint",
"project_id": "uuid",
"status": "\"pending\" on creation",
"connector_name": "string | null",
"return_url": "string | null",
"mode": "\"api\" | \"assistant\"",
"phone_number": "string | null",
"expires_at": "ISO timestamp"
}Fields9
connect_urlconnect_tokenproject_idstatusconnector_namereturn_urlmodephone_numberexpires_atCode Examples
Send the returned connect_url to your customer however you like: an email, a button in your own dashboard, a QR code. It requires no Ainvented login on their side. Pass their number when you know it.
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/connect" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"connector_name": "Acme Support",
"phone_number": "+34 600 111 222",
"return_url": "https://acme.example/settings/whatsapp?done=1"
}'
# → { "connect_url": "https://ainvented.com/connect/whatsapp/DlhaNJ_Jyaf...",
# "connect_token": "DlhaNJ_Jyaf...",
# "status": "pending",
# "phone_number": "+34600111222",
# "expires_at": "2026-08-31T20:17:38.262Z" }Details
Errors
- 403 admin_key_required — the key is bound to a project. Everything under
/v1/projects/**is account management and needs an Admin key. - 403 whatsapp_not_enabled — the account is not approved for the WhatsApp endpoints. Every route under
/whatsapp/returns this for a non-reseller account. - 403 project_disabled — the project was deleted.
- 400 — bad project id, a
return_urlthat is not http(s), or amodeother than the two above. - 400 invalid_phone_number — a
phone_numberthat is not a number with its country code (8 to 15 digits). Nothing is minted. - 503 whatsapp_not_configured — WhatsApp onboarding is not switched on for this deployment. Never a client bug; retry later.
Check connect links
Lists the connect links issued for this project, newest first, so you can tell whether a customer finished. Poll it after handing over a link, or read it on demand when your customer returns to your app.
Authentication
Bearer <admin_api_key> — same requirements as the POST.
Request Schema
JSON type shape
{
"status": "\"pending\" | \"completed\" | \"failed\"",
"limit": "integer",
"offset": "integer"
}Fields3
statuslimitoffsetResponse Schema
JSON type shape
{
"data[].connect_token": "the token from the POST response",
"data[].status": "\"pending\" (issued, unused) | \"completed\" (connected) | \"failed\" (an attempt failed; the link still works and they can retry) | \"expired\" (past expires_at)",
"data[].connector_id": "uuid | null",
"data[].connector_name": "string | null",
"data[].mode": "\"api\" | \"assistant\"",
"data[].phone_number": "string | null",
"data[].error_message": "string | null",
"data[].created_at": "ISO timestamp",
"data[].expires_at": "ISO timestamp",
"data[].completed_at": "ISO timestamp | null",
"page": "{ limit, offset, has_more }"
}Fields11
data[].connect_tokendata[].statusdata[].connector_iddata[].connector_namedata[].modedata[].phone_numberdata[].error_messagedata[].created_atdata[].expires_atdata[].completed_atpageCode Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/connect?status=completed" \
-H "Authorization: Bearer $ADMIN_KEY"Details
List connected accounts
The WhatsApp accounts attached to this project, with their mode, how many people have written to each and how many of your webhooks fire for them. Inactive accounts are hidden unless asked for.
Authentication
Bearer <admin_api_key> — Admin key, project owner, reseller account. Same for every endpoint below.
Request Schema
JSON type shape
{
"mode": "\"api\" | \"assistant\"",
"include_inactive": "true"
}Fields2
modeinclude_inactiveResponse Schema
JSON type shape
{
"data[].id": "uuid",
"data[].name": "string",
"data[].mode": "\"api\" | \"assistant\"",
"data[].display_phone_number": "string | null",
"data[].verified_name": "string | null",
"data[].phone_number_id": "string | null",
"data[].business_account_id": "string | null",
"data[].onboarded_via": "\"embedded_signup\" | \"manual\" | null",
"data[].is_active": "boolean",
"data[].token_expires_at": "ISO timestamp | null",
"data[].needs_reconnect": "boolean",
"data[].connected_at": "ISO timestamp",
"data[].conversation_count": "integer",
"data[].last_inbound_at": "ISO timestamp | null",
"data[].webhook_count": "integer"
}Fields15
data[].iddata[].namedata[].modedata[].display_phone_numberdata[].verified_namedata[].phone_number_iddata[].business_account_iddata[].onboarded_viadata[].is_activedata[].token_expires_atdata[].needs_reconnectdata[].connected_atdata[].conversation_countdata[].last_inbound_atdata[].webhook_countCode Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/accounts?mode=api" \
-H "Authorization: Bearer $ADMIN_KEY"Read an account
One connected account with the same fields as the listing. 404 account_not_found for an account of another project — an account id never resolves across projects.
Authentication
Bearer <admin_api_key>
Response Schema
JSON type shape
{
"…": "the same object as one row of the listing"
}Fields1
…Code Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID" \
-H "Authorization: Bearer $ADMIN_KEY"Update an account
Rename an account, switch its mode, deactivate it, or give a manually configured account its WhatsApp Business Account id. Switching an account connected from the AI Chat view — or before modes existed — to API mode is how it stops answering by itself and starts reaching your webhooks; the customer does not reconnect. Every change is written to the project's audit log.
Authentication
Bearer <admin_api_key>
Request Schema
JSON type shape
{
"name": "string",
"mode": "\"api\" | \"assistant\"",
"is_active": "boolean",
"business_account_id": "string"
}Fields4
namemodeis_activebusiness_account_idResponse Schema
JSON type shape
{
"…": "the updated account, same shape as the listing"
}Fields1
…Code Examples
curl -X PUT "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{ "mode": "api" }'Details
Errors
- 400 — nothing to update, a
modeother than the two, or abusiness_account_idthat is not numeric. - 400 business_account_unverified — WhatsApp does not let the account's token read that business account; nothing is stored. Check the id in WhatsApp Manager, or reconnect the number through a connect link.
- 409 business_account_already_set — the account already carries its business account id (every connect-link account does).
- 404 account_not_found — not an account of this project.
- 403 project_disabled — the project was deleted.
Who wrote in
One row per phone that has written to one of the project's API-mode accounts, most recent message first. A customer who writes to two of your numbers is two conversations. This is also the list of phones you may send free-form messages to.
Authentication
Bearer <admin_api_key>
Request Schema
JSON type shape
{
"account_id": "uuid",
"phone": "string",
"since": "ISO datetime",
"limit": "integer",
"offset": "integer"
}Fields5
account_idphonesincelimitoffsetResponse Schema
JSON type shape
{
"data[].id": "uuid",
"data[].account_id": "uuid",
"data[].phone": "string",
"data[].profile_name": "string | null",
"data[].first_inbound_at": "ISO timestamp | null",
"data[].last_inbound_at": "ISO timestamp | null",
"data[].last_outbound_at": "ISO timestamp | null",
"data[].inbound_count": "integer",
"data[].outbound_count": "integer",
"data[].last_message": "{ direction: \"inbound\" | \"outbound\", preview: string } | null",
"page": "{ limit, offset, has_more }"
}Fields11
data[].iddata[].account_iddata[].phonedata[].profile_namedata[].first_inbound_atdata[].last_inbound_atdata[].last_outbound_atdata[].inbound_countdata[].outbound_countdata[].last_messagepageCode Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/conversations?account_id=$ACCOUNT_ID&since=$(date -u +%Y-%m-%dT00:00:00Z)" \
-H "Authorization: Bearer $ADMIN_KEY"Read messages
Every message on the project's API-mode accounts, in both directions, newest first: what customers sent, what you sent, and what failed to send. Every inbound message is stored BEFORE any webhook delivery is attempted, so this is your fallback when your endpoint was down — filter on since and order=asc to catch up. GET /whatsapp/messages/{messageId} returns one message with its full payload.
Authentication
Bearer <admin_api_key>
Request Schema
JSON type shape
{
"account_id": "uuid",
"conversation_id": "uuid",
"phone": "string",
"direction": "\"inbound\" | \"outbound\"",
"type": "text | image | audio | video | document | sticker | location | contacts | reaction | interactive | button | order | template | unsupported | unknown",
"status": "received | sent | delivered | read | failed",
"since": "ISO datetime",
"until": "ISO datetime",
"order": "\"desc\" (default) | \"asc\"",
"include_payload": "true",
"limit": "integer",
"offset": "integer"
}Fields12
account_idconversation_idphonedirectiontypestatussinceuntilorderinclude_payloadlimitoffsetResponse Schema
JSON type shape
{
"data[].id": "uuid",
"data[].account_id": "uuid",
"data[].conversation_id": "uuid",
"data[].direction": "\"inbound\" | \"outbound\"",
"data[].wa_message_id": "string | null",
"data[].from": "string",
"data[].to": "string",
"data[].type": "string",
"data[].text": "string | null",
"data[].media": "{ id, mime_type, sha256, filename?, voice?, animated? } | null",
"data[].status": "\"received\" for inbound; \"sent\" → \"delivered\" → \"read\", or \"failed\", for outbound",
"data[].error": "{ code, message } | null",
"data[].sent_at": "ISO timestamp",
"data[].delivered_at": "ISO timestamp | null",
"data[].read_at": "ISO timestamp | null",
"data[].webhook": "{ status: \"none\" | \"pending\" | \"delivered\" | \"failed\", delivered_at } for inbound messages; null for outbound",
"data[].api_key_id": "uuid | null",
"data[].created_at": "ISO timestamp",
"data[].referral": "object | null",
"data[].payload": "object",
"page": "{ limit, offset, has_more }"
}Fields21
data[].iddata[].account_iddata[].conversation_iddata[].directiondata[].wa_message_iddata[].fromdata[].todata[].typedata[].textdata[].mediadata[].statusdata[].errordata[].sent_atdata[].delivered_atdata[].read_atdata[].webhookdata[].api_key_iddata[].created_atdata[].referraldata[].payloadpageCode Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/messages?direction=inbound&since=2026-09-03T08:00:00Z&order=asc&limit=200" \
-H "Authorization: Bearer $ADMIN_KEY"A "contacts" message: text carries the names, payload the phones (wa_id included), emails, organisation and addresses exactly as WhatsApp sent them. "location", "interactive", "button", "reaction" and "order" work the same way — the type-specific block sits in payload under the type's own key.
{
"id": "…", "direction": "inbound", "type": "contacts", "text": "Ana Pérez",
"media": null, "referral": null,
"payload": {
"from": "573156399415", "id": "wamid.HBgL…", "timestamp": "1789246740", "type": "contacts",
"contacts": [{
"name": { "formatted_name": "Ana Pérez", "first_name": "Ana", "last_name": "Pérez" },
"phones": [{ "phone": "+57 315 639 9415", "type": "CELL", "wa_id": "573156399415" }],
"emails": [{ "email": "ana@acme.example", "type": "WORK" }],
"org": { "company": "Acme", "title": "Sales" }
}]
}
}referral is present on the first message of a customer who tapped a Click-to-WhatsApp ad or the WhatsApp button of a post. ctwa_clid is the click id you hand to Meta's Conversions API to attribute the sale.
{
"id": "…", "direction": "inbound", "type": "text", "text": "¡Hola! Quiero más información",
"referral": {
"source_url": "https://fb.me/2XyZ…", "source_id": "120212345678901234", "source_type": "ad",
"headline": "Varimarket Shop", "body": "Tus pasteles nunca volverán a verse simples…",
"media_type": "image", "image_url": "https://scontent.xx.fbcdn.net/…", "ctwa_clid": "ARAkGf…"
}
}Send a message
Sends a message from one of the project's API-mode accounts. A free-form message (text, media or interactive) can only go to a phone that has written to that account, and WhatsApp itself refuses it once 24 hours have passed since the customer's last message. A template message may go to any phone and opens the conversation. The message is stored either way — a refused send is a message with status "failed" and its reason — and nothing is generated on your behalf: you decide every word. Interactive messages — reply buttons, a pick-one list, a call-to-action link, a request for the customer's location — take the interactive object in the shape WhatsApp itself uses; the customer's answer arrives as an inbound message of type "interactive" whose payload carries the id of the button or row they pressed.
Authentication
Bearer <admin_api_key> — also subject to the key's rate limit (429 rate_limit_exceeded with Retry-After).
Request Schema
JSON type shape
{
"account_id": "uuid",
"to": "string",
"type": "\"text\" (default) | \"image\" | \"audio\" | \"video\" | \"document\" | \"sticker\" | \"template\" | \"interactive\"",
"text": "string (max 4096)",
"media_url": "https url",
"filename": "string",
"template": "{ name, language, components? }",
"interactive": "{ type, header?, body, footer?, action }",
"reply_to": "string",
"preview_url": "boolean"
}Fields10
account_idtotypetextmedia_urlfilenametemplateinteractivereply_topreview_urlResponse Schema
JSON type shape
{
"…": "the stored outbound message, same shape as a row of GET /whatsapp/messages, status \"sent\", HTTP 201"
}Fields1
…Code Examples
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/messages" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "'$ACCOUNT_ID'",
"to": "+34 600 111 222",
"text": "Your order 4521 ships tomorrow. Anything else we can help with?",
"reply_to": "wamid.HBhMMzQ2MDAxMTEyMjIVAgASGBQzQTZDMEE5MDQ1QjE4MDU1RkMyMwA="
}'
# → 201 { "id": "…", "direction": "outbound", "status": "sent", "wa_message_id": "wamid.…", … }curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/messages" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "'$ACCOUNT_ID'",
"to": "34600111222",
"type": "document",
"media_url": "https://acme.example/invoices/4521.pdf",
"filename": "invoice-4521.pdf",
"text": "Here is your invoice."
}'curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/messages" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "'$ACCOUNT_ID'",
"to": "34600111222",
"type": "template",
"template": { "name": "order_update", "language": "es",
"components": [{ "type": "body", "parameters": [{ "type": "text", "text": "4521" }] }] }
}'What the customer taps comes back as an inbound message of type "interactive": text is the button's title and payload.interactive.button_reply.id the id you gave it.
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/messages" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "'$ACCOUNT_ID'",
"to": "34600111222",
"type": "interactive",
"interactive": {
"type": "button",
"header": { "type": "text", "text": "Pedido 4521" },
"body": { "text": "Tu pedido está listo. ¿Confirmamos la entrega para mañana?" },
"footer": { "text": "Acme" },
"action": { "buttons": [
{ "type": "reply", "reply": { "id": "confirm-4521", "title": "Sí, mañana" } },
{ "type": "reply", "reply": { "id": "reschedule-4521", "title": "Otro día" } }
] }
}
}'
# → 201 { "type": "interactive", "text": "Tu pedido está listo. ¿Confirmamos la entrega para mañana?", "status": "sent", … }
# later, on your webhook: { "event": "whatsapp.message.received", "data": { "message": { "type": "interactive", "text": "Sí, mañana",
# "payload": { "interactive": { "type": "button_reply", "button_reply": { "id": "confirm-4521", "title": "Sí, mañana" } }, … } } } }curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/messages" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_id": "'$ACCOUNT_ID'",
"to": "34600111222",
"type": "interactive",
"interactive": {
"type": "list",
"body": { "text": "Elige la franja de entrega." },
"action": { "button": "Ver franjas", "sections": [
{ "title": "Mañana", "rows": [ { "id": "slot-am", "title": "9:00 – 13:00" } ] },
{ "title": "Tarde", "rows": [ { "id": "slot-pm", "title": "16:00 – 20:00", "description": "Última franja del día" } ] }
] }
}
}'
# the answer: type "interactive", text "9:00 – 13:00", payload.interactive.list_reply.id "slot-am"{
"error": {
"message": "The 24-hour customer service window for this phone has closed. Send an approved template to reopen the conversation.",
"type": "api_error",
"code": "whatsapp_send_failed",
"details": { "whatsapp_code": 131047, "whatsapp_message": "(#131047) Re-engagement message",
"retryable": false, "message_id": "…the failed row, readable in GET /whatsapp/messages…" }
}
}Details
Errors
- 400 — the offending field is named in
error.param: a text message without text, a media type without an httpsmedia_url, a template type withouttemplate, atothat is not a phone; for an interactive message the whole path (interactive.action.buttons.0.reply.title) — a fourth button, a title over 20 characters, an eleventh row, a media header on a list, two rows with the same id — so WhatsApp's own refusal (131009) is never the first you hear of it. - 404 conversation_not_found — a free-form message to a phone that never wrote to this account. Send a template instead.
- 404 account_not_found — not an account of this project.
- 409 account_not_api_mode — the assistant answers on this account; switch it with the PUT above.
- 409 account_inactive — deactivated account.
- 409 account_reauthorization_required — the customer's authorization expired or was revoked. Mint a new connect link and have them reconnect; the account keeps its id and history.
- 502 whatsapp_send_failed — WhatsApp refused the message;
details.whatsapp_codesays why anddetails.retryablewhether waiting helps. - 502 whatsapp_unreachable — the WhatsApp API did not answer in time. Nothing was sent; retry.
- 429 rate_limit_exceeded — your key's bucket is empty; honour
Retry-After.
Download media
The bytes of an image, audio, video, document or sticker a customer sent. Inbound messages carry media.id; fetching it needs the account's authorization, which never leaves the server, so this endpoint fetches it for you and streams the file back with its content type. Media stays available on WhatsApp for a limited time — download what you need to keep.
Authentication
Bearer <admin_api_key>
Request Schema
JSON type shape
{
"account_id": "uuid"
}Fields1
account_idResponse Schema
JSON type shape
{
"body": "the file bytes",
"Content-Type": "the media's type, e.g. image/jpeg, audio/ogg, application/pdf",
"Content-Length": "bytes",
"X-WhatsApp-Media-Sha256": "hex digest reported by WhatsApp, when available"
}Fields4
bodyContent-TypeContent-LengthX-WhatsApp-Media-Sha256Code Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/media/$MEDIA_ID?account_id=$ACCOUNT_ID" \
-H "Authorization: Bearer $ADMIN_KEY" -o photo.jpgDetails
Errors
- 404 media_not_found — unknown id, or the file has expired on WhatsApp.
- 413 media_too_large — over the size limit (25 MB by default).
- 409 account_reauthorization_required — the account's authorization is no longer valid.
- 502 whatsapp_unreachable / whatsapp_media_failed — WhatsApp did not return the file; retry.
List templates
The message templates of one connected account, read live from its WhatsApp Business Account: name, language, category, review status, components and quality. A template is the only message WhatsApp lets you send to a phone that has not written in, or after the 24-hour window has closed (POST /whatsapp/messages with type "template"), so this is where you check what is approved before sending. Nothing is cached on Ainvented: WhatsApp is the source of truth. Pages are cursor-based — pass next_cursor back as after.
Authentication
Bearer <admin_api_key> — reseller-only, like every route under /whatsapp/. Works for accounts in either mode: templates belong to the business account, not to the way the number answers.
Request Schema
JSON type shape
{
"status": "\"APPROVED\" | \"PENDING\" | \"REJECTED\" | \"PAUSED\" | \"DISABLED\" | \"IN_APPEAL\" | \"PENDING_DELETION\" | \"DELETED\" | \"LIMIT_EXCEEDED\"",
"category": "\"MARKETING\" | \"UTILITY\" | \"AUTHENTICATION\"",
"language": "string",
"name": "string",
"search": "string",
"limit": "integer 1-100",
"after": "string"
}Fields7
statuscategorylanguagenamesearchlimitafterResponse Schema
JSON type shape
{
"data[].id": "string",
"data[].account_id": "uuid",
"data[].name": "string",
"data[].language": "string",
"data[].status": "\"APPROVED\" | \"PENDING\" | \"REJECTED\" | \"PAUSED\" | \"DISABLED\" | \"IN_APPEAL\" | \"PENDING_DELETION\" | \"DELETED\" | \"LIMIT_EXCEEDED\"",
"data[].category": "\"MARKETING\" | \"UTILITY\" | \"AUTHENTICATION\"",
"data[].sub_category": "string | null",
"data[].components": "array",
"data[].parameter_format": "\"POSITIONAL\" | \"NAMED\" | null",
"data[].message_send_ttl_seconds": "integer | null",
"data[].quality": "{ score: \"GREEN\" | \"YELLOW\" | \"RED\" | \"UNKNOWN\", updated_at: ISO timestamp | null, reasons } | null",
"data[].rejected_reason": "string | null",
"data[].previous_category": "string | null",
"data[].correct_category": "string | null",
"page.limit": "integer",
"page.cursor": "string | null",
"page.next_cursor": "string | null",
"page.has_more": "boolean"
}Fields18
data[].iddata[].account_iddata[].namedata[].languagedata[].statusdata[].categorydata[].sub_categorydata[].componentsdata[].parameter_formatdata[].message_send_ttl_secondsdata[].qualitydata[].rejected_reasondata[].previous_categorydata[].correct_categorypage.limitpage.cursorpage.next_cursorpage.has_moreCode Examples
Only an APPROVED template can be sent. Filter on it before offering the list to your own users.
curl "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates?status=approved&limit=50" \
-H "Authorization: Bearer $ADMIN_KEY"
# → { "data": [ { "id": "1011820805234855", "name": "order_update", "language": "es", "status": "APPROVED",
# "category": "UTILITY", "components": [ { "type": "BODY", "text": "Hola {{1}}, tu pedido {{2}} sale mañana." } ], … } ],
# "page": { "limit": 50, "cursor": null, "next_cursor": null, "has_more": false } }curl "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates?limit=25&after=$NEXT_CURSOR" \
-H "Authorization: Bearer $ADMIN_KEY"Details
Errors shared by every template endpoint
- 404 account_not_found — the account is not on this project.
- 409 account_inactive — the account is switched off; templates are managed on live accounts only.
- 409 account_reauthorization_required — the account's authorization has expired; mint a connect link and have the customer reconnect.
- 409 business_account_unknown — the account was connected by hand and carries no WhatsApp Business Account id. Set it once with
PUT /whatsapp/accounts/{accountId}andbusiness_account_id(it is stored only after WhatsApp confirms the account's own token can read it), or reconnect the number through a connect link, which records it by itself. - 400 whatsapp_template_refused — WhatsApp refused the request;
error.messagecarries its own explanation (a name already in use, a variable without an example value, a category that does not fit the text…) anderror.detailsitswhatsapp_code/whatsapp_subcode. - 404 template_not_found — no template with that id on this account. An id from another account answers this too, whatever the token could reach.
- 403 whatsapp_permission_denied — the account's token cannot manage templates; reconnect through a connect link.
- 429 whatsapp_rate_limited — WhatsApp is throttling template operations on this account (it caps creations per hour); retry after
Retry-After.429 rate_limit_exceededis your own key's limit, as on every write. - 502 whatsapp_template_failed / whatsapp_unreachable — WhatsApp did not answer or answered with an outage;
error.details.retryableis true. On a create, read the list before retrying: the template may exist.
Create a template
Submits a message template to WhatsApp for review on the account's business account. WhatsApp reviews it asynchronously — usually within minutes, sometimes longer: the template comes back with status PENDING, and the outcome (APPROVED or REJECTED with a reason) reaches you as a whatsapp.template.status webhook event and on GET. Nothing is generated on your behalf: the text is yours, and WhatsApp judges it against its template policies.
Authentication
Bearer <admin_api_key> — subject to the key's rate limit (429 rate_limit_exceeded with Retry-After).
Request Schema
JSON type shape
{
"name": "string",
"category": "\"MARKETING\" | \"UTILITY\" | \"AUTHENTICATION\"",
"language": "string",
"components": "array",
"app_id": "string",
"allow_category_change": "boolean",
"parameter_format": "\"POSITIONAL\" | \"NAMED\"",
"message_send_ttl_seconds": "integer"
}Fields8
namecategorylanguagecomponentsapp_idallow_category_changeparameter_formatmessage_send_ttl_secondsResponse Schema
JSON type shape
{
"…": "the template, same shape as a row of GET /templates, with status \"PENDING\" (or already \"APPROVED\" for some utility texts WhatsApp clears at once), HTTP 201"
}Fields1
…Code Examples
The example values are what WhatsApp's reviewers see in place of the variables; the template is refused without them.
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_update",
"category": "UTILITY",
"language": "es",
"components": [
{ "type": "BODY",
"text": "Hola {{1}}, tu pedido {{2}} sale mañana. ¿Necesitas algo más?",
"example": { "body_text": [["Ana", "4521"]] } },
{ "type": "FOOTER", "text": "Acme" },
{ "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Sí, gracias" } ] }
]
}'
# → 201 { "id": "1011820805234855", "name": "order_update", "language": "es", "status": "PENDING", "category": "UTILITY", … }
# later, on your webhook: { "event": "whatsapp.template.status", "data": { "template": { "id": "1011820805234855", … }, "status": "APPROVED", … } }Give the header its sample as a public URL: the file is fetched, uploaded to WhatsApp and the handle put in its place before the template is submitted — nothing to copy between calls. The same works on an edit (PUT).
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "spring_sale",
"category": "MARKETING",
"language": "es",
"components": [
{ "type": "HEADER", "format": "IMAGE", "example": { "header_url": "https://acme.example/img/spring-hero.jpg" } },
{ "type": "BODY", "text": "Hola {{1}}, llegó la primavera: 20% en todo hasta el domingo.", "example": { "body_text": [["Ana"]] } }
]
}'
# → 201 { "id": "…", "status": "PENDING", "components": [ { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["4::…"] } }, … ] }The two-call form: a media header with a header_handle example — the handle POST …/templates/media answers with for a sample file (its header_component is exactly the first component below). Buttons with a URL may carry one variable at the end of the link.
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "spring_sale",
"category": "MARKETING",
"language": "en_US",
"allow_category_change": true,
"components": [
{ "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["4::aW1hZ2UvanBlZw==:ARZ…"] } },
{ "type": "BODY", "text": "Spring is here, {{1}}. 20% off everything until Sunday.", "example": { "body_text": [["Ana"]] } },
{ "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "Shop now", "url": "https://acme.example/sale/{{1}}", "example": ["ana-20"] } ] }
]
}'Details
What WhatsApp enforces
- Review is asynchronous. Listen to
whatsapp.template.statusor pollGET /templates/{templateId}; do not send a template until it isAPPROVED— a send of a pending or rejected template is refused withwhatsapp_send_failed. - One name, several languages. Creating the same name in a second language is a second template with its own id and its own review; send it with the matching
template.language. - Limits are the account's. WhatsApp caps how many templates a business account may hold and how many can be created per hour; the refusal comes back as
whatsapp_template_refusedorwhatsapp_rate_limited. - Quality follows the template. Recipients who block or report the number lower its quality; a
REDtemplate can bePAUSEDand thenDISABLEDby WhatsApp — both arrive aswhatsapp.template.statusevents, andwhatsapp.template.qualityreports the rating changes themselves. - Nothing is billed by Ainvented. A template call is free at WhatsApp and unpriced here; every create, edit and delete is written to the project's audit log with the key that made it.
Upload a header sample
The sample file a template with an IMAGE, VIDEO or DOCUMENT header is reviewed against. WhatsApp takes it through its own upload and hands back a handle; this endpoint does that upload with the account's authorization — which never leaves the server — and answers with the handle, plus the HEADER component ready to paste into POST /templates. If the sample sits at a public URL you can skip this call: put it in the header's example.header_url when creating or editing the template and the upload happens there. Hand the file over as multipart/form-data (a file part) or as a public https url this server fetches. WhatsApp accepts JPEG and PNG (up to 5 MB), MP4 (16 MB) and PDF (100 MB); this server buffers up to 25 MB by default. A handle is tied to the account's app and expires after a while at WhatsApp, so upload right before creating the template.
Authentication
Bearer <admin_api_key> — subject to the key's rate limit (429 rate_limit_exceeded with Retry-After).
Request Schema
JSON type shape
{
"file": "multipart part",
"url": "https url (JSON body, instead of file)",
"file_name": "string",
"mime_type": "string",
"app_id": "string"
}Fields5
fileurlfile_namemime_typeapp_idResponse Schema
JSON type shape
{
"handle": "string",
"account_id": "uuid",
"format": "\"IMAGE\" | \"VIDEO\" | \"DOCUMENT\"",
"mime_type": "string",
"size": "integer",
"file_name": "string",
"header_component": "{ type: \"HEADER\", format, example: { header_handle: [handle] } }"
}Fields7
handleaccount_idformatmime_typesizefile_nameheader_componentCode Examples
HANDLE=$(curl -s -X POST "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates/media" \
-H "Authorization: Bearer $ADMIN_KEY" \
-F "file=@hero.jpg;type=image/jpeg" | jq -r .handle)
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "spring_sale",
"category": "MARKETING",
"language": "es",
"components": [
{ "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["'$HANDLE'"] } },
{ "type": "BODY", "text": "Hola {{1}}, llegó la primavera: 20% en todo hasta el domingo.", "example": { "body_text": [["Ana"]] } }
]
}'curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates/media" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://acme.example/brochures/spring-2026.pdf" }'
# → 201 { "handle": "4::YXBwbGljYXRpb24vcGRm:ARZ…", "format": "DOCUMENT", "mime_type": "application/pdf", "size": 184213,
# "file_name": "spring-2026.pdf", "header_component": { "type": "HEADER", "format": "DOCUMENT", "example": { "header_handle": ["4::…"] } } }Details
Errors
- 400 — no
filepart and nourl; an empty file (media_empty); aurlthat is not public https, or that could not be fetched (sample_unreachable);app_id_requiredfor an account you configured by hand; a malformedapp_id. - 415 unsupported_media_type — not JPEG, PNG, MP4 or PDF.
- 413 media_too_large — over WhatsApp's cap for the format, or over this server's buffer.
- 404 account_not_found · 409 account_inactive / account_reauthorization_required / business_account_unknown — the same account rules as every template call.
- 403 whatsapp_permission_denied — the account's token cannot upload on that app (a hand-made account: check
app_id). - 502 whatsapp_template_failed / whatsapp_unreachable — WhatsApp did not take the file; retry.
- 503 whatsapp_upload_unavailable — uploads are not configured on this server.
Read a template
One template of the account, by the id WhatsApp gave it — the same id the whatsapp.template.* events carry, so a webhook delivery can be followed up with this call. The id is looked up under this account's business account first: another account's template answers 404 template_not_found.
Authentication
Bearer <admin_api_key>
Response Schema
JSON type shape
{
"…": "the template, same shape as a row of GET /templates"
}Fields1
…Code Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates/$TEMPLATE_ID" \
-H "Authorization: Bearer $ADMIN_KEY"
# → { "id": "…", "name": "order_update", "language": "es", "status": "REJECTED", "rejected_reason": "INVALID_FORMAT", … }Edit a template
Changes the components, the category, the parameter format or the delivery TTL of one template. WhatsApp only edits a template that is APPROVED, REJECTED or PAUSED — never one PENDING or DISABLED — allows an approved template one edit a day and ten a month, and sends any change of the text back to review: the answer is the template as WhatsApp now holds it, usually PENDING again. The id is looked up under this account's business account first.
Authentication
Bearer <admin_api_key> — subject to the key's rate limit.
Request Schema
JSON type shape
{
"components": "array",
"category": "\"MARKETING\" | \"UTILITY\" | \"AUTHENTICATION\"",
"parameter_format": "\"POSITIONAL\" | \"NAMED\"",
"message_send_ttl_seconds": "integer"
}Fields4
componentscategoryparameter_formatmessage_send_ttl_secondsResponse Schema
JSON type shape
{
"…": "the template after the change, same shape as a row of GET /templates"
}Fields1
…Code Examples
curl -X PUT "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates/$TEMPLATE_ID" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"components": [
{ "type": "BODY", "text": "Hola {{1}}, tu pedido {{2}} sale mañana.", "example": { "body_text": [["Ana", "4521"]] } }
]
}'
# → 200 { "id": "…", "status": "PENDING", … } ← reviewed again; the whatsapp.template.status event tells the outcomeDelete a template
Deletes one template — that name in that language — from the account's business account. WhatsApp moves it to PENDING_DELETION (messages already sent with it still deliver for a while), and the name cannot be reused for 30 days. To delete a name in every language at once, call DELETE /whatsapp/accounts/{accountId}/templates?name={name} instead. The id is looked up under this account's business account first.
Authentication
Bearer <admin_api_key> — subject to the key's rate limit.
Response Schema
JSON type shape
{
"deleted": "true",
"account_id": "uuid",
"id": "string | null",
"name": "string",
"language": "string | null"
}Fields5
deletedaccount_ididnamelanguageCode Examples
curl -X DELETE "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates/$TEMPLATE_ID" \
-H "Authorization: Bearer $ADMIN_KEY"
# → { "deleted": true, "account_id": "…", "id": "1011820805234855", "name": "order_update", "language": "es" }curl -X DELETE "$BASE/api/v1/projects/$PID/whatsapp/accounts/$ACCOUNT_ID/templates?name=order_update" \
-H "Authorization: Bearer $ADMIN_KEY"
# → { "deleted": true, "account_id": "…", "id": null, "name": "order_update", "language": null }Register a webhook
Where inbound messages of the project's API-mode accounts are delivered, and optionally the delivery statuses of the messages you send. A hook may listen to every account of the project or to one account. It is a project webhook — same signature, retries and auto-disable rules as the budget hooks — and its secret is returned once, here.
Authentication
Bearer <admin_api_key>
Request Schema
JSON type shape
{
"url": "https url",
"account_id": "uuid | null",
"events": "[\"whatsapp.message.received\", \"whatsapp.message.status\", \"whatsapp.template.status\", \"whatsapp.template.category\", \"whatsapp.template.quality\"]"
}Fields3
urlaccount_ideventsResponse Schema
JSON type shape
{
"id": "uuid",
"url": "string",
"account_id": "uuid | null",
"events": "string[]",
"is_active": "boolean",
"secret": "hex string",
"created_at": "ISO timestamp",
"updated_at": "ISO timestamp",
"last_delivery_at": "ISO timestamp | null",
"failure_count": "integer"
}Fields10
idurlaccount_ideventsis_activesecretcreated_atupdated_atlast_delivery_atfailure_countCode Examples
curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/webhooks" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://acme.example/whatsapp/inbound",
"account_id": "'$ACCOUNT_ID'",
"events": ["whatsapp.message.received", "whatsapp.message.status"]
}'
# → 201 { "id": "…", "secret": "0f3a…", … } ← store the secret nowManage webhooks
Lists the project's WhatsApp webhooks (budget hooks of the same project are not shown here, nor are these shown as WhatsApp hooks elsewhere). Each one is also reachable at /whatsapp/webhooks/{webhookId}: GET reads it, PUT changes url, events, account_id, is_active or rotates the secret, DELETE deactivates it, and POST /whatsapp/webhooks/{webhookId}/test sends a signed sample event with data.test = true so you can check your endpoint before real traffic.
Authentication
Bearer <admin_api_key>
Request Schema
JSON type shape
{
"account_id": "uuid",
"include_disabled": "true"
}Fields2
account_idinclude_disabledResponse Schema
JSON type shape
{
"data[]": "the webhook objects, without secrets"
}Fields1
data[]Code Examples
curl -X PUT "$BASE/api/v1/projects/$PID/whatsapp/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{ "rotate_secret": true }'
# → 200 { …, "secret": "new hex" }curl -X POST "$BASE/api/v1/projects/$PID/whatsapp/webhooks/$WEBHOOK_ID/test" \
-H "Authorization: Bearer $ADMIN_KEY"
# → 202 { "delivered": true, "attempts": 1, "event_id": "…" }curl -X DELETE "$BASE/api/v1/projects/$PID/whatsapp/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $ADMIN_KEY"
# → 204Traffic of a project
Messages per day on one project — received, sent and failed — zero-filled over the window, plus how many people wrote and how many numbers are active. One grouped query whatever the volume; the Partner Console draws its WhatsApp chart from it.
Authentication
Bearer Admin API key — reseller accounts only.
Request Schema
JSON type shape
{
"from": "string",
"to": "string",
"group_by": "string",
"account_id": "string"
}Fields4
fromtogroup_byaccount_idResponse Schema
JSON type shape
{
"project_id": "string",
"window": {
"from": "string",
"to": "string"
},
"group_by": "string",
"totals": {
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer",
"active_conversations": "integer",
"accounts": "integer"
},
"series": [
{
"bucket": "string",
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer"
}
],
"by_account": [
{
"account_id": "string",
"project_id": "string",
"name": "string | null",
"display_phone_number": "string | null",
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer"
}
]
}Fields27
project_idwindowfromtogroup_bytotalsinboundoutboundtotalfailedactive_conversationsaccountsseriesbucketinboundoutboundtotalfailedby_accountaccount_idproject_idnamedisplay_phone_numberinboundoutboundtotalfailedCode Examples
curl "$BASE/api/v1/projects/$PID/whatsapp/traffic?from=2026-08-01&to=2026-08-31&group_by=account" \
-H "Authorization: Bearer $API_KEY"{
"project_id": "…",
"window": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-09-01T00:00:00.000Z" },
"group_by": "account",
"totals": { "inbound": 412, "outbound": 388, "total": 800, "failed": 3, "active_conversations": 96, "accounts": 2 },
"series": [
{ "bucket": "2026-08-01", "inbound": 14, "outbound": 12, "total": 26, "failed": 0 },
{ "bucket": "2026-08-02", "inbound": 0, "outbound": 0, "total": 0, "failed": 0 }
],
"by_account": [
{ "account_id": "…", "project_id": "…", "name": "Acme Support", "display_phone_number": "+1 555 111 1111", "inbound": 400, "outbound": 380, "total": 780, "failed": 3 }
]
}Every number, all projects
Every WhatsApp number connected to any of your projects, in one paged list with its project, its mode and how many people wrote to it. The account-wide counterpart of the per-project list — one call for a thousand projects, never one per project.
Authentication
Bearer Admin API key — reseller accounts only.
Request Schema
JSON type shape
{
"mode": "string",
"include_inactive": "boolean",
"project_ids": "string",
"limit": "integer",
"offset": "integer"
}Fields5
modeinclude_inactiveproject_idslimitoffsetResponse Schema
JSON type shape
{
"data": [
{
"id": "string",
"project_id": "string",
"name": "string",
"mode": "string",
"display_phone_number": "string | null",
"verified_name": "string | null",
"is_active": "boolean",
"needs_reconnect": "boolean",
"conversation_count": "integer",
"last_inbound_at": "string | null",
"webhook_count": "integer",
"project": {
"id": "string",
"name": "string | null"
}
}
],
"page": {
"limit": "integer",
"offset": "integer",
"has_more": "boolean"
}
}Fields19
dataidproject_idnamemodedisplay_phone_numberverified_nameis_activeneeds_reconnectconversation_countlast_inbound_atwebhook_countprojectidnamepagelimitoffsethas_moreCode Examples
curl "$BASE/api/v1/whatsapp/accounts?mode=api&limit=100" \
-H "Authorization: Bearer $API_KEY"Bulk mode / active
Set who answers — and whether a number is active — on every WhatsApp number of your projects in one call, or on a selection by project and/or by number. One transaction; one whatsapp.account.update audit row (marked bulk) per number whose stored value actually changes; a re-apply writes nothing.
Authentication
Bearer Admin API key — reseller accounts only.
Request Schema
JSON type shape
{
"mode": "string",
"is_active": "boolean",
"project_ids": "string[]",
"account_ids": "string[]"
}Fields4
modeis_activeproject_idsaccount_idsResponse Schema
JSON type shape
{
"matched": "integer",
"updated": "integer",
"mode": "string",
"is_active": "boolean"
}Fields4
matchedupdatedmodeis_activeCode Examples
curl -X PUT "$BASE/api/v1/whatsapp/accounts" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{ "mode": "api", "project_ids": ["$PID"] }'{ "matched": 3, "updated": 2, "mode": "api" }Traffic, all projects
The same report as the per-project traffic, across every project you own (or a project_ids selection), with an optional per-project breakdown. Every figure comes from a grouped query on the message index — never from message rows — so it costs the same for one project as for a thousand.
Authentication
Bearer Admin API key — reseller accounts only.
Request Schema
JSON type shape
{
"from": "string",
"to": "string",
"group_by": "string",
"project_ids": "string",
"account_id": "string"
}Fields5
fromtogroup_byproject_idsaccount_idResponse Schema
JSON type shape
{
"project_id": "null",
"project_count": "integer",
"window": {
"from": "string",
"to": "string"
},
"group_by": "string",
"totals": {
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer",
"active_conversations": "integer",
"accounts": "integer"
},
"series": [
{
"bucket": "string",
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer"
}
],
"by_project": [
{
"project_id": "string",
"name": "string | null",
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer"
}
],
"by_account": [
{
"account_id": "string",
"project_id": "string",
"name": "string | null",
"display_phone_number": "string | null",
"inbound": "integer",
"outbound": "integer",
"total": "integer",
"failed": "integer"
}
]
}Fields35
project_idproject_countwindowfromtogroup_bytotalsinboundoutboundtotalfailedactive_conversationsaccountsseriesbucketinboundoutboundtotalfailedby_projectproject_idnameinboundoutboundtotalfailedby_accountaccount_idproject_idnamedisplay_phone_numberinboundoutboundtotalfailedCode Examples
curl "$BASE/api/v1/whatsapp/traffic?group_by=project" \
-H "Authorization: Bearer $API_KEY"Webhook on every project
Register one webhook URL on every project you own (or a project_ids selection) in a single call. One secret is minted for the whole batch and returned once, so an application that receives every customer's messages at one endpoint verifies every delivery with one key. A project that already has an active project-wide hook on that URL is left alone and reported as reused.
Authentication
Bearer Admin API key — reseller accounts only.
Request Schema
JSON type shape
{
"url": "string",
"events": "string[]",
"project_ids": "string[]"
}Fields3
urleventsproject_idsResponse Schema
JSON type shape
{
"secret": "string | null",
"created": "integer",
"reused": "integer",
"webhooks": [
{
"id": "string",
"project_id": "string",
"url": "string",
"events": "string[]",
"is_active": "boolean",
"reused": "boolean",
"created_at": "string"
}
]
}Fields11
secretcreatedreusedwebhooksidproject_idurleventsis_activereusedcreated_atCode Examples
curl -X POST "$BASE/api/v1/whatsapp/webhooks" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{ "url": "https://acme.example/whatsapp/inbound", "events": ["whatsapp.message.received", "whatsapp.message.status"] }'{
"secret": "9b1f…",
"created": 41,
"reused": 2,
"webhooks": [
{ "id": "…", "project_id": "…", "url": "https://acme.example/whatsapp/inbound", "events": ["whatsapp.message.received", "whatsapp.message.status"], "is_active": true, "reused": false, "created_at": "2026-09-03T10:00:00.000Z" }
]
}Webhook payload & signature
Every delivery is a JSON POST with the headers X-Ainvented-Event, X-Ainvented-Delivery (the event id) and X-Ainvented-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body under your webhook's secret. Verify it before trusting a payload. Answer with any 2xx within 8 seconds; anything else is retried once, 2 seconds later, and the message is marked webhook.status = "failed" for you to read back. Deliveries are at-least-once and idempotent on the message id, so a duplicate event carries the same data.message.id.
POST https://acme.example/whatsapp/inbound
X-Ainvented-Event: whatsapp.message.received
X-Ainvented-Delivery: 3f6c1a2e-…
X-Ainvented-Signature: sha256=9b1f…
{
"id": "3f6c1a2e-…",
"event": "whatsapp.message.received",
"occurred_at": "2026-09-03T10:15:02.114Z",
"project_id": "…",
"data": {
"message": {
"id": "…", "account_id": "…", "conversation_id": "…",
"direction": "inbound", "wa_message_id": "wamid.…",
"from": "34600111222", "to": "15551111111",
"type": "image", "text": "is this the blue one?",
"media": { "id": "1042…", "mime_type": "image/jpeg", "sha256": "…" },
"status": "received", "error": null,
"sent_at": "2026-09-03T10:15:00.000Z", "delivered_at": null, "read_at": null,
"webhook": { "status": "pending", "delivered_at": null },
"api_key_id": null, "created_at": "2026-09-03T10:15:02.010Z",
"referral": null,
"payload": { "from": "34600111222", "id": "wamid.…", "timestamp": "1788776100", "type": "image",
"image": { "id": "1042…", "mime_type": "image/jpeg", "sha256": "…", "caption": "is this the blue one?" } }
},
"account": { "id": "…", "name": "Acme Support", "display_phone_number": "+1 555 111 1111", "phone_number_id": "…" },
"conversation": { "id": "…", "phone": "34600111222", "profile_name": "Ana", "inbound_count": 3, "outbound_count": 2, "…": "…" }
}
}data.message.payload is the message exactly as WhatsApp delivered it (since 2026-09-16, on every event — the same object include_payload=true returns). The first-class fields summarise; the payload carries the whole content of the types that do not fit a text: the phones, emails and organisation of a contacts card, the coordinates of a location, the id of the button or row pressed in an interactive reply (payload.interactive.button_reply.id / list_reply.id), a button tapped on a template, a reaction with the id of the message it reacts to, an order with its items — and any field WhatsApp adds later, without waiting for us to model it. data.message.referral is the ad or post the customer came from, or null.
A whatsapp.message.status event carries data.status (sent, delivered, read or failed) and the outbound data.message it refers to, already updated.
The template events carry data.template (id, name, language) and data.account (with its business_account_id). whatsapp.template.status adds data.status (APPROVED, REJECTED, PAUSED, DISABLED, PENDING_DELETION…), data.reason and, on a pause or a disable, data.info and data.disabled_at; whatsapp.template.category adds previous_category, new_category and correct_category; whatsapp.template.quality adds previous_quality_score and new_quality_score. Deliveries are idempotent on the template, the new state and the moment WhatsApp reported it. Follow any of them up with GET /whatsapp/accounts/{accountId}/templates/{templateId}.
{
"id": "8a1d…", "event": "whatsapp.template.status", "occurred_at": "2026-09-10T18:43:36.000Z", "project_id": "…",
"data": {
"template": { "id": "1011820805234855", "name": "order_update", "language": "es" },
"status": "APPROVED", "reason": null, "disabled_at": null, "info": null,
"account": { "id": "…", "name": "Acme Support", "display_phone_number": "+1 555 111 1111", "phone_number_id": "…", "business_account_id": "…" }
}
}# Node — verify a delivery
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
const ok = expected.length === signature.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));What your customer goes through
The page you send them is hosted by Ainvented and needs no account. They sign in with Meta, choose or create a WhatsApp Business account, and verify a phone number. Meta asks them for a payment method: as a technology provider there is no credit line to share, so WhatsApp bills each customer directly for their own message usage. If the link carries their number, the page shows it and goes straight to Meta; otherwise it asks them for the number first (recommended, not required).
Limits worth designing around
- Give us the number. Meta tells us an account was shared, not by whom. With
phone_numberon the link, the share is matched to it exactly — the connection completes even if your customer closes our page before it finishes, however many customers are connecting at the same time. Without it, only the page they keep open can finish the link, and they may be asked for the last digits of their number. - The number must be free. A phone number already registered on the WhatsApp Business API cannot be onboarded, and your customer must be able to receive Meta's verification code on it.
- One number, one project. A number already active on a different project is refused with
phone_number_in_use. - Reconnecting is the same call. If the same number comes back to the same project, the existing connector is refreshed in place rather than duplicated.
- The access token does not expire, so your customers are never asked to reconnect on a schedule.
- 24-hour window. WhatsApp only allows free-form replies within 24 hours of the end user's message. An assistant answers immediately so this rarely bites it; in API mode, a reply that comes later than that is refused with
whatsapp_send_failed(code 131047) and only a template reopens the conversation. - Templates are managed here too. Create them with
POST /whatsapp/accounts/{accountId}/templates, learn the review outcome from thewhatsapp.template.statusevent, then send them by name withtype: "template". An account connected by hand needs itsbusiness_account_idset once (PUT /whatsapp/accounts/{accountId}) before its templates can be managed.
Project API keys
Each project may have multiple API keys, each scoped to that project. Keys are hashed with Argon2id; only the last 4 characters (partialKey) are stored for display. The full key is returned exactly once at creation.
Create an API key under a project
Creates a new ApiKey row scoped to the project. Returns the full key once.
Authentication
Bearer <api_key> — must own the project.
Request Schema
JSON type shape
{
"label": "string"
}Fields1
labelResponse Schema
JSON type shape
{
"id": "uuid",
"key": "full key",
"partialKey": "last 4 chars",
"label": "string",
"projectId": "uuid",
"createdAt": "ISO"
}Fields6
idkeypartialKeylabelprojectIdcreatedAtCode Examples
curl -X POST $BASE/api/v1/projects/$PID/api-keys \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "prod-server-1" }'List API keys for a project
Returns active keys by default. Append ?include_revoked=true to also see revoked keys.
Authentication
Bearer <api_key> — must own the project.
Response Schema
JSON type shape
{
"keys": [
{
"id": "uuid",
"label": "string",
"partialKey": "last 4 chars",
"projectId": "uuid",
"createdAt": "ISO",
"lastUsedAt": "ISO | null",
"revokedAt": "ISO | null",
"requestCount": "number",
"tokenUsage": "string (BigInt as string)"
}
],
"total": "number"
}Fields11
keysidlabelpartialKeyprojectIdcreatedAtlastUsedAtrevokedAtrequestCounttokenUsagetotalCode Examples
curl "$BASE/api/v1/projects/$PID/api-keys?include_revoked=true" -H "Authorization: Bearer $API_KEY"Revoke an API key
Sets revokedAt on the key. Subsequent calls using that key return 401. Already-revoked → 410. Cross-project mismatch → 404. Usage history is retained.
Authentication
Bearer <api_key> — must own the project.
Code Examples
curl -X DELETE $BASE/api/v1/projects/$PID/api-keys/$KEY_ID -H "Authorization: Bearer $API_KEY"Consumption
Aggregates token + cost usage across your project. Each billable sub-call (completion, workflow, skill, assistant, connector) is recorded as its own usage event, so the reported totals always match what your project actually consumed.
Read consumption breakdown
Returns a window of token + cost usage with a per-component breakdown and a time series. Window may not exceed 90 days. Defaults to the last 30 days UTC.
Authentication
Bearer <api_key> — must own the project.
Request Schema
JSON type shape
{
"from": "ISO timestamp",
"to": "ISO timestamp",
"group_by": "\"day\" | \"component\" | \"model\"",
"component_type": "\"completion\" | \"workflow\" | \"skill\" | \"assistant\" | \"connector\"",
"model": "\"ainvented-default\" | \"ainvented-low\" | \"ainvented-saga\" | \"ainvented-epic\" | \"(none)\""
}Fields5
fromtogroup_bycomponent_typemodelResponse Schema
JSON type shape
{
"project_id": "uuid",
"currency": "string",
"budget_cents": "number",
"consumed_cents": "number",
"remaining_cents": "number",
"remaining_pct": "number",
"budget_micros": "number",
"consumed_micros": "number",
"remaining_micros": "number",
"exhausted": "boolean",
"hard_cap": "boolean",
"alert_thresholds": "number[]",
"fired_thresholds": "number[]",
"token_limit": "number",
"consumed_tokens": "number",
"remaining_tokens": "number",
"remaining_tokens_pct": "number",
"token_hard_cap": "boolean",
"fired_token_thresholds": "number[]",
"window": {
"from": "ISO",
"to": "ISO"
},
"totals": {
"prompt_tokens": "number",
"completion_tokens": "number",
"total_tokens": "number",
"cached_tokens": "number",
"cost_cents": "number",
"cost_micros": "number"
},
"by_component": {
"completion": {
"events": "number",
"prompt_tokens": "number",
"completion_tokens": "number",
"cached_tokens": "number",
"total_tokens": "number",
"cost_cents": "number"
},
"workflow": "...same shape...",
"skill": "...",
"assistant": "...",
"connector": "..."
},
"tokens_by_component": {
"completion": "number",
"workflow": "number",
"skill": "number",
"assistant": "number",
"connector": "number"
},
"by_model": {
"ainvented-default": {
"events": "number",
"prompt_tokens": "number",
"completion_tokens": "number",
"cached_tokens": "number",
"total_tokens": "number",
"cost_cents": "number",
"cost_micros": "number"
},
"ainvented-low": "...same shape...",
"(none)": "...auxiliary calls with no billed model..."
},
"series": [
{
"bucket": "string",
"prompt_tokens": "number",
"completion_tokens": "number",
"cached_tokens": "number",
"total_tokens": "number",
"cost_cents": "number",
"cost_micros": "number"
}
]
}Fields66
project_idcurrencybudget_centsconsumed_centsremaining_centsremaining_pctbudget_microsconsumed_microsremaining_microsexhaustedhard_capalert_thresholdsfired_thresholdstoken_limitconsumed_tokensremaining_tokensremaining_tokens_pcttoken_hard_capfired_token_thresholdswindowfromtototalsprompt_tokenscompletion_tokenstotal_tokenscached_tokenscost_centscost_microsby_componentcompletioneventsprompt_tokenscompletion_tokenscached_tokenstotal_tokenscost_centsworkflowskillassistantconnectortokens_by_componentcompletionworkflowskillassistantconnectorby_modelainvented-defaulteventsprompt_tokenscompletion_tokenscached_tokenstotal_tokenscost_centscost_microsainvented-low(none)seriesbucketprompt_tokenscompletion_tokenscached_tokenstotal_tokenscost_centscost_microsCode Examples
Last 7 days, grouped by component, only workflow events.
FROM=$(node -p "new Date(Date.now() - 7*864e5).toISOString()")
curl "$BASE/api/v1/projects/$PID/consumption?from=$FROM&group_by=component&component_type=workflow" \
-H "Authorization: Bearer $API_KEY"Scope the whole report (totals, by_component, by_model, series) to a single model.
curl "$BASE/api/v1/projects/$PID/consumption?model=ainvented-low" \
-H "Authorization: Bearer $API_KEY"Read a project's authoritative balance
Single source of truth for 'does this key/project have money?'. Money is reported at floored-cent precision (budget_cents/consumed_cents/remaining_cents, backward-compatible) AND exact micro precision (budget_micros/consumed_micros/remaining_micros; 10000 micros = 1 cent). The `exhausted` flag is computed from the SAME comparison the request-time gate uses, so polling this never disagrees with the 402 a key actually receives. IMPORTANT: a project-scoped hard-cap key spends ONLY this project budget — it never falls back to the user balance. Not admin-gated: a project-scoped key may read its own balance.
Authentication
Bearer <api_key> — must own the project.
Response Schema
JSON type shape
{
"project_id": "uuid",
"budget_cents": "number",
"consumed_cents": "number",
"remaining_cents": "number",
"budget_micros": "number",
"consumed_micros": "number",
"remaining_micros": "number",
"exhausted": "boolean",
"remaining_pct": "number",
"currency": "string",
"hard_cap": "boolean",
"token_limit": "number",
"consumed_tokens": "number",
"remaining_tokens": "number",
"token_hard_cap": "boolean"
}Fields15
project_idbudget_centsconsumed_centsremaining_centsbudget_microsconsumed_microsremaining_microsexhaustedremaining_pctcurrencyhard_captoken_limitconsumed_tokensremaining_tokenstoken_hard_capCode Examples
Check whether a project-scoped key still has budget before relying on it.
curl "$BASE/api/v1/projects/$PID/balance" -H "Authorization: Bearer $API_KEY"Promotions
Promo codes and referral share links. GET /api/promotions/resolve is fully public (it powers the /promo/<slug> landing pages) and returns a display-safe offer summary. Redeeming a code and reading your referral stats are browser-session endpoints: they authenticate with the session cookie of your signed-in ainvented account — not available with API keys. Money fields follow the platform conventions: offer credit amounts are USD dollars; caps, minimums and commission totals are integer cents.
Resolve a promo code or share-link slug
Resolves a promo code or a share-link landing slug to a display-safe offer summary. Lookups always answer HTTP 200 with { valid, reason, offer } so a landing page can render the outcome honestly — including why an offer is not redeemable ('not_found' | 'inactive' | 'not_started' | 'expired' | 'fully_redeemed'). offer is null only when reason is 'not_found'. The only 400 is omitting both query parameters. Rate-limited per IP (30 requests/minute).
Authentication
None — public endpoint. No API key and no session required.
Request Schema
JSON type shape
{
"code": "string",
"slug": "string"
}Fields2
codeslugResponse Schema
JSON type shape
{
"valid": "boolean",
"reason": "string | null",
"offer": {
"code": "string",
"offerKind": "string",
"creditAmount": "number | null",
"discountPercent": "number | null",
"discountCapCents": "integer | null",
"minTopupCents": "integer | null",
"slug": "string | null",
"appliesAtSignup": "boolean",
"appliesAtReload": "boolean",
"expiresAt": "string | null"
}
}Fields13
validreasonoffercodeofferKindcreditAmountdiscountPercentdiscountCapCentsminTopupCentsslugappliesAtSignupappliesAtReloadexpiresAtCode Examples
Resolve a promo code (case-insensitive).
curl "$BASE/api/promotions/resolve?code=WELCOME10"
# Response — 200 OK
# {
# "valid": true,
# "reason": null,
# "offer": {
# "code": "WELCOME10",
# "offerKind": "credit",
# "creditAmount": 10,
# "discountPercent": null,
# "discountCapCents": null,
# "minTopupCents": null,
# "slug": "welcome",
# "appliesAtSignup": true,
# "appliesAtReload": true,
# "expiresAt": null
# }
# }Resolve a landing-page slug (slug wins when both are sent).
curl "$BASE/api/promotions/resolve?slug=welcome"
# Same response shape as resolving by code. The /promo/welcome landing
# page uses exactly this call to render the offer.Unknown or expired offers are 200s with valid:false; only a missing code AND slug is a 400.
# An unknown code is NOT an HTTP error — the lookup outcome is in the body:
curl "$BASE/api/promotions/resolve?code=NO-SUCH-CODE"
# Response — 200 OK
# { "valid": false, "reason": "not_found", "offer": null }
# An expired (or inactive / not-started / fully-redeemed) offer still returns
# its display-safe summary so a landing page can render an honest message:
# { "valid": false, "reason": "expired", "offer": { "code": "SUMMER24", ... } }
# Omitting BOTH query parameters is the only 400:
curl "$BASE/api/promotions/resolve"
# Response — 400 Bad Request
# { "error": { "message": "code or slug is required", "type": "invalid_request" } }Redeem a promo code
Redeems a promo code for the signed-in user. A 'credit' offer credits your USD balance instantly; a 'reload_discount' offer records a claim that is applied automatically to your next qualifying top-up. Each user can redeem a given code at most once, and redemption caps are enforced atomically. Same-origin requests only (CSRF protection), rate-limited to 10 attempts/minute per user.
Authentication
Session cookie required (browser session) — not available with API keys.
Request Schema
JSON type shape
{
"code": "string"
}Fields1
codeResponse Schema
JSON type shape
{
"success": "boolean",
"offerKind": "string",
"creditAmount": "string",
"newBalance": "string",
"discountPercent": "string | null",
"message": "string"
}Fields6
successofferKindcreditAmountnewBalancediscountPercentmessageCode Examples
Redeem a credit or reload-discount code with your browser session.
# Runs with your signed-in browser session cookie (see Authentication above).
curl -X POST $BASE/api/billing/redeem-promo \
-H "Content-Type: application/json" \
-b "authjs.session-token=<your browser session cookie>" \
-d '{ "code": "WELCOME10" }'
# Response — 200 OK (credit offer: balance credited instantly)
# { "success": true, "offerKind": "credit", "creditAmount": "10", "newBalance": "12.50" }
# Response — 200 OK (reload_discount offer: claim saved, applied on your next top-up)
# {
# "success": true,
# "offerKind": "reload_discount",
# "discountPercent": "20",
# "message": "Discount saved — it will apply to your next reload."
# }This endpoint reports errors as a flat { "error": "<message>" } body.
# Errors use a flat { "error": "<message>" } body on this endpoint.
# Response — 401 Unauthorized (no browser session)
# { "error": "Authentication required" }
# Response — 404 Not Found (unknown code)
# { "error": "Invalid promo code." }
# Response — 400 Bad Request (each returned as its own message):
# { "error": "You have already redeemed this promo code." }
# { "error": "This promo code is no longer active." }
# { "error": "This promo code has expired." }
# { "error": "This promo code is not active yet." }
# { "error": "This promo code has been fully redeemed." }
# Response — 429 Too Many Requests (more than 10 attempts/minute)Your referral stats & share link
Returns the signed-in user's referral summary for the Share & Earn view: whether you are enrolled as a promoter, your shareable link, how many users you have referred, and your commission totals in integer cents. Enrollment is automatic when the Share & Earn program is enabled (your first call provisions your link); otherwise it is admin-managed. Non-enrolled users receive asPromoter:false with zeroed totals — never an error. The response shape is identical in every case.
Authentication
Session cookie required (browser session) — not available with API keys.
Response Schema
JSON type shape
{
"data": {
"asPromoter": "boolean",
"shareUrl": "string | null",
"referredCount": "number",
"commission": {
"accruedCashCents": "integer",
"paidCashCents": "integer",
"autoCreditedCents": "integer",
"currency": "string"
}
},
"generatedAt": "string"
}Fields10
dataasPromotershareUrlreferredCountcommissionaccruedCashCentspaidCashCentsautoCreditedCentscurrencygeneratedAtCode Examples
Read your own referral stats (enrolled and not-enrolled shapes shown).
# Runs with your signed-in browser session cookie (see Authentication above).
curl "$BASE/api/referrals/me" \
-b "authjs.session-token=<your browser session cookie>"
# Response — 200 OK (enrolled promoter)
# {
# "data": {
# "asPromoter": true,
# "shareUrl": "https://ainvented.com/r/9c1f4c1e-0000-4000-8000-000000000000",
# "referredCount": 3,
# "commission": {
# "accruedCashCents": 1500,
# "paidCashCents": 200,
# "autoCreditedCents": 0,
# "currency": "USD"
# }
# },
# "generatedAt": "2026-07-01T12:00:00.000Z"
# }
# Response — 200 OK (not enrolled)
# {
# "data": { "asPromoter": false, "shareUrl": null, "referredCount": 0,
# "commission": { "accruedCashCents": 0, "paidCashCents": 0,
# "autoCreditedCents": 0, "currency": "USD" } },
# "generatedAt": "2026-07-01T12:00:00.000Z"
# }curl "$BASE/api/referrals/me"
# Response — 401 Unauthorized (no browser session)
# { "error": { "message": "Authentication required", "type": "auth_error" } }Vector Stores
Use Ainvented as a vector store. A store is a named collection of documents in your project's vector space. Ingest documents (text, URL, or file) — they are chunked and embedded — then run semantic search, optionally with a RAG-generated answer.
Node.js client (example)
Node 18+ can call the REST endpoints directly with its built-in fetch. This complete example creates a store, adds reusable text, checks every HTTP response, and runs a semantic query—no extra client library required:
const headers = {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
}
async function request(path, options = {}) {
const response = await fetch(`https://ainvented.com${path}`, { headers, ...options })
if (!response.ok) throw new Error(`Ainvented API ${response.status}: ${await response.text()}`)
return response.json()
}
const store = await request('/api/v1/vector-stores', {
method: 'POST', body: JSON.stringify({ name: 'product-docs' }),
})
await request(`/api/v1/vector-stores/${store.id}/documents`, {
method: 'POST', body: JSON.stringify({ text: 'Ainvented can store reusable knowledge.' }),
})
const result = await request(`/api/v1/vector-stores/${store.id}/query`, {
method: 'POST', body: JSON.stringify({ query: 'How does it work?', top_k: 5, answer: true }),
})
console.log(result.answer, result.results)Create / list / get stores
Create a store (local, zero-cost — reserves a tag). GET /v1/vector-stores lists; GET /v1/vector-stores/{id} retrieves; POST /v1/vector-stores/{id} updates name/description; all are local.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"name": "string",
"description": "string",
"project_id": "uuid"
}Fields3
namedescriptionproject_idResponse Schema
JSON type shape
{
"id": "string (cuid)",
"name": "string",
"description": "string|null",
"tag": "string (vs:<id>)",
"status": "\"active\" | \"archived\"",
"project_id": "uuid",
"document_count": "number",
"created_at": "ISO",
"updated_at": "ISO"
}Fields9
idnamedescriptiontagstatusproject_iddocument_countcreated_atupdated_atCode Examples
Create a store.
curl -X POST "$BASE/api/v1/vector-stores" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"name":"product-docs","description":"Docs for RAG"}'List active stores (?status=archived|all, ?limit, ?cursor, ?order).
curl "$BASE/api/v1/vector-stores" -H "Authorization: Bearer $API_KEY"Add / list documents
Add a document via JSON (text or url) or multipart (file ≤100MB). Raw text is stored as a .txt document. Embedding tokens are metered. Very large text-heavy files may take up to 10 minutes to embed. GET lists documents (?status=ready|pending|failed|archived|all).
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"text": "string",
"url": "string (url)",
"file (multipart)": "binary",
"title": "string",
"tags": "string[]",
"chunk_size": "int",
"chunk_overlap": "int",
"metadata": "object",
"generate_metadata": "boolean"
}Fields9
texturlfile (multipart)titletagschunk_sizechunk_overlapmetadatagenerate_metadataResponse Schema
JSON type shape
{
"id": "string",
"store_id": "string",
"kind": "\"text\"|\"url\"|\"file\"",
"title": "string|null",
"doc_uid": "string|null",
"source": "string|null",
"char_count": "number",
"chunk_count": "number",
"embed_tokens": "number",
"status": "\"ready\"|\"failed\"",
"error_code": "string|null",
"created_at": "ISO"
}Fields12
idstore_idkindtitledoc_uidsourcechar_countchunk_countembed_tokensstatuserror_codecreated_atCode Examples
Embed a text blob.
curl -X POST "$BASE/api/v1/vector-stores/$SID/documents" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"text":"Ainvented can be used as a vector store.","chunk_size":800,"chunk_overlap":100}'Attach filterable key→value metadata to every chunk (optional).
curl -X POST "$BASE/api/v1/vector-stores/$SID/documents" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"text":"Q4 revenue grew 12%.","metadata":{"team":"finance","year":2024}}'Opt in to LLM-extracted topics/summary/keywords/entities (extra audited cost). Merged into every chunk and filterable.
curl -X POST "$BASE/api/v1/vector-stores/$SID/documents" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"text":"TaskFlow Pro is $12/seat; invoices are emailed monthly.","generate_metadata":true}'Multipart file upload.
curl -X POST "$BASE/api/v1/vector-stores/$SID/documents" \
-H "Authorization: Bearer $API_KEY" -F 'file=@/path/to/doc.pdf'Multipart `metadata` form field — a JSON-object string. Malformed/non-object values are ignored (never an error).
curl -X POST "$BASE/api/v1/vector-stores/$SID/documents" \
-H "Authorization: Bearer $API_KEY" \
-F 'file=@/path/to/doc.pdf' -F 'metadata={"team":"finance","year":2024}'Details
Per-chunk metadata (optional)
Attach arbitrary metadata (a JSON object of key→value pairs) when adding a document and it is stored on every chunk of that document. You can then narrow a search to matching chunks with the query metadata_filter (see below). Pass it as a JSON body field for text/url adds, or as a multipart metadata form field (a JSON-object string) for file uploads. A malformed or non-object multipart metadata value is silently ignored — never an error.
Supported file types
Uploads are chunked + embedded (text is extracted; audio is transcribed; images are embedded for visual search). Unknown extensions are ingested as best-effort plain text. Max 100 MB. Very large text-heavy files may take up to 10 minutes to embed.
- 📄 Text & Office:
.pdf.docx.pptx.xlsx.xls.csv.json.jsonl.txt.md - 💻 Code & config:
.py.js.ts.tsx.jsx.java.cpp.c.h.cs.php.rb.go.rs.swift.kt.scala.r.sh.bash.sql.xml.yaml.yml.toml.ini.cfg.conf.css.scss.sass.less - 🖼️ Images:
.png.jpg.jpeg.gif.webp.bmp.tiff.svg - 🔊 Audio:
.mp3.wav.m4a.ogg.flac.aac - 🎬 Video:
.mp4.mov.webm.mkv.avi.3gp.mpeg.flv.wmv— up to 50 MB (413 video_too_largeabove it). Read as a text record (summary, timestamped visual timeline with on-screen text, transcript) that is chunked and searchable like any document. - 🌐 Web: pass
url(JSON body) for an HTTP/HTTPS page — text plus extracted images/audio. A link to a video file, or a public YouTube link, is read as a video.
Query — semantic search (+ optional RAG answer)
Embeds the query and returns ranked chunks. Set answer:true to also generate a grounded answer from the retrieved chunks (a second, billable generation step). optimize_query:true adds a billable query rewrite.
Authentication
Bearer <api_key>
Request Schema
JSON type shape
{
"query": "string",
"top_k": "int",
"threshold": "number",
"optimize_query": "boolean",
"tags": "string[]",
"answer": "boolean (optional",
"max_tokens": "int",
"metadata_filter": "Array<{ key: string, op?: \"eq\"|\"neq\"|\"in\"|\"contains\"|\"gt\"|\"gte\"|\"lt\"|\"lte\"|\"exists\"|\"not_exists\", value?: any }> . AND-ed pre-filters applied BEFORE the semantic search: the matching chunks are selected first and ranked exactly by similarity, so a chunk that matches is never dropped by the approximate index",
"text_contains": "string"
}Fields9
querytop_kthresholdoptimize_querytagsanswermax_tokensmetadata_filtertext_containsResponse Schema
JSON type shape
{
"results": "[{ text, title, source, score, metadata, ... }]",
"count": "number",
"answer": "string (only when answer:true)",
"usage": {
"total_tokens": "number"
}
}Fields5
resultscountanswerusagetotal_tokensCode Examples
Top-3 semantic search.
curl -X POST "$BASE/api/v1/vector-stores/$SID/query" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"query":"How do I use Ainvented as a vector store?","top_k":3}'Map-reduce pre-filter: AND-ed metadata predicates + a text substring, applied before the semantic search (optional).
curl -X POST "$BASE/api/v1/vector-stores/$SID/query" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"query":"revenue","top_k":5,
"metadata_filter":[{"key":"team","op":"eq","value":"finance"},
{"key":"year","op":"gte","value":2024}],
"text_contains":"Q4"}'Search + grounded answer.
curl -X POST "$BASE/api/v1/vector-stores/$SID/query" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{"query":"Summarize the docs","answer":true,"max_tokens":150}'Details
Map-reduce pre-filters (optional)
metadata_filter is an array of AND-ed predicates (≤20), each { key, op?, value? }. Supported op values: eq (default) neq in contains gt gte lt lte exists not_exists. exists and not_exists test for the presence/absence of the key and take no value; in takes an array of values. text_contains (≤500 chars) keeps only chunks whose text contains that substring. Both are applied before the semantic search (the “map” step), then the usual top_k/threshold ranking runs over what survives.
Delete a store or a document
DELETE /v1/vector-stores/{id} deletes the store and removes its documents from search. DELETE /v1/vector-stores/{id}/documents/{docId} removes a single document — precisely that one, even when other documents share its filename.
Authentication
Bearer <api_key>
Response Schema
JSON type shape
{
"id": "string",
"status": "\"archived\"",
"deleted": "true",
"collateral_archived": "number (document delete only)"
}Fields4
idstatusdeletedcollateral_archivedCode Examples
Archive a store.
curl -X DELETE "$BASE/api/v1/vector-stores/$SID" -H "Authorization: Bearer $API_KEY"Removes exactly this document, whatever else shares its filename.
curl -X DELETE "$BASE/api/v1/vector-stores/$SID/documents/$DOC_ID" \
-H "Authorization: Bearer $API_KEY"
# => {"id":"...","status":"archived","deleted":true,"collateral_archived":0}Details
Deleting one document among duplicates
Uploading the same file twice creates two documents, with the same title and source but different ids. Each carries its own doc_uid, and a delete matches on that — so removing one copy never touches the other, and collateral_archived comes back 0.
Cost & metering
Adding a document, searching, and generating an answer each consume tokens that are metered against your project's budget and token quota — one usage event per billable call, so your Consumption totals always match what you actually used. Local operations (create, rename, list, delete) are free.
Webhooks
Register HTTPS endpoints to receive notifications when a project crosses a budget threshold (50%, 80%, 95%, 100% by default), exhausts its budget, or — opt-in — on every recorded usage event. Deliveries are signed with HMAC-SHA256 over the raw body using the secret returned at registration. Each delivery is idempotent on a payload hash so retries do not duplicate. URLs must be https:// and cannot resolve to RFC1918 / loopback / link-local / multicast addresses.
Register a webhook
Creates a webhook registration. The signing secret is returned ONCE in the response and is never readable again — store it securely.
Authentication
Bearer <api_key> — must own the project. Project must not be disabled.
Request Schema
JSON type shape
{
"url": "string",
"events": "(\"budget.threshold\" | \"budget.exhausted\" | \"tokens.threshold\" | \"tokens.exhausted\" | \"usage.recorded\")[]"
}Fields2
urleventsResponse Schema
JSON type shape
{
"id": "uuid",
"url": "string",
"events": "string[]",
"is_active": "boolean",
"secret": "string",
"created_at": "ISO"
}Fields6
idurleventsis_activesecretcreated_atCode Examples
curl -X POST $BASE/api/v1/projects/$PID/webhooks \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.your-app.com/budget", "events": ["budget.threshold","budget.exhausted"] }'List webhooks
Lists the project's active webhooks. Secrets are NEVER returned by list.
Authentication
Bearer <api_key> — must own the project.
Response Schema
JSON type shape
{
"data": [
{
"id": "uuid",
"url": "string",
"events": "string[]",
"is_active": "boolean",
"created_at": "ISO",
"last_delivery_at": "ISO | null",
"failure_count": "number"
}
]
}Fields8
dataidurleventsis_activecreated_atlast_delivery_atfailure_countCode Examples
curl $BASE/api/v1/projects/$PID/webhooks -H "Authorization: Bearer $API_KEY"Update a webhook (incl. rotate secret)
Patches url, events, or is_active. Pass rotate_secret: true to issue a new signing secret — the new secret is returned ONCE in the response and the old one stops verifying immediately. Empty patch returns 400.
Authentication
Bearer <api_key> — must own the project.
Request Schema
JSON type shape
{
"url": "string",
"events": "string[]",
"is_active": "boolean",
"rotate_secret": "boolean"
}Fields4
urleventsis_activerotate_secretResponse Schema
JSON type shape
{
"id": "uuid",
"url": "string",
"events": "string[]",
"is_active": "boolean",
"secret": "string (only present when rotate_secret was true)"
}Fields5
idurleventsis_activesecretCode Examples
curl -X PUT $BASE/api/v1/projects/$PID/webhooks/$WH_ID \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "rotate_secret": true }'Delete a webhook
Stops all deliveries to the webhook. Idempotent: a second call returns 410.
Authentication
Bearer <api_key> — must own the project.
Code Examples
curl -X DELETE $BASE/api/v1/projects/$PID/webhooks/$WH_ID -H "Authorization: Bearer $API_KEY"Test fire a webhook
Sends a synthetic budget.threshold payload to the registered URL with the same signing scheme as production deliveries. Useful for verifying signature handling on the receiving side.
Authentication
Bearer <api_key> — must own the project. Webhook must be active.
Response Schema
JSON type shape
{
"delivered": "boolean",
"attempts": "number"
}Fields2
deliveredattemptsCode Examples
curl -X POST $BASE/api/v1/projects/$PID/webhooks/$WH_ID/test \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Webhook payload & signature
Every delivery sends the following headers and a JSON body. Verify the signature using HMAC-SHA256 over the raw request body with the webhook's secret.
X-Ainvented-Event— event type, e.g.budget.thresholdX-Ainvented-Delivery— unique delivery UUIDX-Ainvented-Signature—sha256=<hex>over the raw bodyUser-Agent—Ainvented-Webhook/1.0
{
"id": "<delivery uuid>",
"event": "budget.threshold",
"occurred_at": "2026-04-29T10:30:00Z",
"project_id": "<uuid>",
"data": {
"currency": "USD",
"budget_cents": 25000,
"consumed_cents": 20000,
"remaining_cents": 5000,
"remaining_pct": 20.0,
"threshold_pct": 80,
"by_component": {
"completion": { "events": 412, "total_tokens": 88000, "cost_cents": 9100 },
"workflow": { "events": 33, "total_tokens": 21000, "cost_cents": 4200 },
"skill": { "events": 71, "total_tokens": 11334, "cost_cents": 2500 },
"assistant": { "events": 18, "total_tokens": 3000, "cost_cents": 1520 }
}
}
}Token-quota events (tokens.threshold / tokens.exhausted) fire when consumed_tokens crosses one of the project's alert_thresholds percentages of token_limit. Each threshold fires at most once per re-arm cycle (re-arm happens automatically when token_limit or alert_thresholds is updated). Payload shape:
{
"id": "<delivery uuid>",
"event": "tokens.threshold",
"occurred_at": "2026-05-14T16:00:00Z",
"project_id": "<uuid>",
"data": {
"currency": "USD",
"token_limit": 1000000,
"consumed_tokens": 800000,
"remaining_tokens": 200000,
"remaining_pct": 20.0,
"threshold_pct": 80,
"by_component": {
"completion": { "events": 412, "total_tokens": 660000, "cost_cents": 9100 },
"workflow": { "events": 33, "total_tokens": 90000, "cost_cents": 4200 }
}
}
}Reliability: 3 retries with exponential backoff (1 s, 4 s, 16 s). Each delivery is recorded in ProjectWebhookDelivery; the payloadHash column makes deliveries idempotent so retries never duplicate. Webhooks are auto-disabled after 20 consecutive failures.
Error Codes
Every failure, on every endpoint, comes back in the same envelope. type names the family, code the specific reason and param the field that caused it when there is one.
{
"error": {
"message": "string - Human-readable error message",
"type": "string - Error type (see Error Codes section)",
"param": "string (optional) - Parameter that caused the error",
"code": "string (optional) - Specific error code"
}
}Bad Request
invalid_request_errorDescription: The request is malformed or contains invalid parameters. This includes validation errors for multimodal content (invalid base64, unsupported formats, size limits exceeded) and for image-generation inputs (see image-gen specific codes below).
context_length_exceeded (param: "messages") — the prompt is larger than the selected model tier's input budget and could not be trimmed without cutting your own messages. The message states how many input tokens the request needs and how many are available. This refusal is NOT billed: it is decided before the model is called, so no tokens are consumed and no usage is recorded. Retry with fewer or shorter messages, fewer attached files, or a tier with more headroom. Requests that can be trimmed succeed instead and report what was dropped on the context_truncation response field.
Image-generation specific codes (all return 400 with type invalid_request_error):
image_modality_unsupported—modalitiescontained a value other thantext/image.invalid_modalities—modalitieswas null or not an array.image_count_out_of_range—image.nwas outside 1..4 or not an integer.image_size_unsupported—image.sizewas not one of the seven allowed values (256x256,512x512,1024x1024,1024x1536,1536x1024,1024x1792,1792x1024).invalid_quality/invalid_style/invalid_response_format— correspondingimage.*field had an unsupported value.invalid_remove_background—image.remove_backgroundwas not a boolean.invalid_image_block—imagewas not a plain object.
502 image-generation specific codes (with type service_unavailable):
image_generation_failed— image generation returned a non-OK status, an empty image list, or fewer images than requested (partial failure = failure).image_background_removal_failed— background removal returned a non-OK status or an invalid response (when background removal is enabled for your project).empty_response/partial_failure/upstream_<status>/fetch_error— finer-grained sub-codes that appear in thecodefield of animage_generation_failedenvelope.
Video codes (400, never billed): invalid_video_url, unsupported_format, video_too_large, too_many_videos, video_unavailable (an explicitly attached link could not be downloaded, or a YouTube link to a video that does not exist, was removed or is private), video_content_rejected (the video may contain restricted content). See Video Content.
Structured output and reasoning (400, never billed): invalid_response_format (param: "response_format") — the value is not one of the three forms, a strict schema breaks a strict-mode rule (the message names it), or it was combined with modalities: ["image"]; invalid_reasoning_option — include_reasoning is not a boolean, or reasoning is not an object with a boolean exclude. See Structured output.
Voice (400, never billed): invalid_model, invalid_input, input_too_long, invalid_language, invalid_speed, invalid_response_format, invalid_file, invalid_file_type, consent_required, voice_read_only, project_mismatch; 413 file_too_large; 404 voice_not_found / voice_project_not_found / generation_not_found; 409 voice_project_archived / duplicate_name. See Voice.
Handling: Check the error message and param field to identify which parameter is invalid. Validate your request against the schema. For multimodal content, ensure proper base64 encoding, supported formats, and size limits.
Unauthorized
authentication_errorDescription: Authentication failed. Invalid, missing, or revoked API key. One exception is not about your key: upstream_unavailable (type server_error) on chat completions or workflow execution is a temporary platform-side problem.
Handling: Verify your API key is correct and hasn't been revoked. Ensure the Authorization header is properly formatted: Bearer YOUR_API_KEY. For upstream_unavailable, keep the key and retry with backoff — nothing was billed.
Forbidden
permission_errorDescription: Insufficient permissions to access the requested resource. Image-gen specific: image_generation_disabled fires when the request explicitly opted in to image output via modalities/tools but image generation is disabled for the project.
Handling: Verify you own the project you're trying to access. Check that your API key has permission for the requested operation. For image_generation_disabled, enable image generation in the AI Chat → Configure pane → "Image Generation" toggle, or remove 'image' from modalities.
Not Found
not_found_errorDescription: The requested resource doesn't exist or doesn't belong to your API key.
Handling: Verify the project ID or session ID exists and belongs to your API key. For sessions, ensure you're using a session ID from a previous response.
Too Many Requests
rate_limit_errorDescription: Rate limit exceeded for your API key.
Handling: Implement exponential backoff. Check the Retry-After header for seconds until reset. Monitor rate limit headers to avoid hitting limits.
Server At Capacity
server_overloadedDescription: Distinct from the per-key rate limit above. Under sustained high concurrency a node may briefly shed new requests to protect the requests already in flight (load-shedding / admission control). The request was not processed, reached no AI model, and incurred no token cost — it is fully safe to retry.
Handling: Honor the Retry-After header and retry with backoff. Because the request did nothing, retrying does not double-bill.
Not Available In Your Region
permission_errorDescription: region_not_supported — the request comes from a country the platform does not serve (judged by the client's network address; for messaging, by the phone number's country). The request was not processed, reached no AI model and is not billed. A WhatsApp or SMS send to a number in such a country answers the same code and nothing is sent.
Handling: Do not retry — the answer will not change. Webhooks, cron and health endpoints are never affected.
Internal Server Error
server_errorDescription: An unexpected error occurred on the server.
Handling: Retry the request with exponential backoff. If the error persists, contact support with the error ID from the response.
Response Format Not Met
service_unavailableresponse_format_failed — every generation of a turn with response_format failed validation (a bounded number of attempts was made). The generations are billed like any other turn. Retry the request; if it keeps failing, simplify the schema or give the model clearer instructions about the keys you expect.
Service Unavailable
service_unavailableDescription: The service is temporarily unavailable due to maintenance or overload.
video_processing_unavailable — a message's video could not be read because video reading was momentarily unavailable. Nothing reached the model and nothing is billed; any video that was already read is cached, so the retry does not pay for it again.
voice_unavailable (503) / voice_timeout (504) — speech, design or transcription could not be completed right now. A failed voice call is not billed; retry.
Handling: Retry after a delay (honor Retry-After). Check status page for maintenance announcements.
Best Practices
The habits that keep an integration fast, cheap and safe.
- Error handling
Always implement proper error handling for all HTTP status codes. Parse error responses to provide meaningful feedback to users.
- Rate limiting
Monitor rate limit headers and implement exponential backoff when approaching limits.
- Session management
Reuse session IDs for multi-turn conversations to maintain context. Store session IDs securely on your backend.
- Streaming
Use streaming mode for better user experience with long responses. Handle SSE parsing correctly and display tokens as they arrive.
- Security
Never expose API keys in client-side code. Always make API calls from your backend. Rotate keys regularly and revoke compromised keys immediately.
- Timeouts
Set appropriate timeouts for your requests (recommended: 60 seconds for completions).
- Multimodal content
Compress images and audio before encoding to reduce token usage. Use appropriate detail levels for images ('low' for simple recognition, 'high' for detailed analysis). Monitor size limits and handle validation errors gracefully.
Additional Resources
Where to go next.
- API Key ManagementCreate, rotate and revoke your API keys.
- Chat projectsCreate and configure the projects these endpoints manage.
- ObservabilityPer-request traces, latency and cost, matched to
X-Request-Id. - BillingYour balance, invoices and project budgets.
- contact@ainvented.comAccess to the reseller surface (payments, WhatsApp) and anything this reference leaves unanswered.