The invoke API

Every deployed agent answers one HTTPS endpoint. You send a prompt, and you get back either one JSON body or a stream of server sent events carrying the agent’s text, tool calls, tool results and steps as they happen.

The endpoint

Every agent has one endpoint:

POST https://api.onecortex.io/v1/agents/{agentId}/invoke

The agent’s page in the dashboard shows the full URL and the agent’s ID, which starts with agt_, each with a copy button.

Authentication

Every call carries an API key as a bearer token:

Authorization: Bearer $ONECORTEX_API_KEY

Create a key under API keys in the dashboard. It is shown once, when you create it. See API keys. A key that is missing, unknown, revoked, expired, or scoped to a different agent is refused with 401 and the same message, A valid Onecortex API key is required., except the last case, which answers 404 so the key never learns that the other agent exists.

The request

A JSON body, at most 1 MB.

string

required

The input to your agent. A request without it is refused with 400 before your agent is called: Request must include a 'prompt' field.

string

Your own key for a conversation, 1 to 256 characters. Send the same value again to reach the same running instance of your agent. Leave it out and Onecortex generates one and returns it. See Sessions.

boolean

true for server sent events, false for one JSON body. Left out, the Accept header decides: text/event-stream streams, anything else (including */*) returns JSON.

array

The conversation as you hold it, for an agent that reads history. Each item is { "role": "...", "content": "..." }.

object

Anything you want your agent to see, at most 4 KB as JSON. Larger is refused with 400: The 'metadata' field can be at most 4 KB.

Every other field you send reaches your agent unchanged, as params, with metadata among them. Onecortex does not decide which of your fields mean something. Each framework page says where params arrive in your code.

Request body

{
  "prompt": "hello",
  "sessionId": "user-42",
  "stream": false,
  "model": "gpt-5",
  "metadata": { "tenant": "acme" }
}

Here, your agent receives params of {"model": "gpt-5", "metadata": {"tenant": "acme"}}.

The JSON response

With stream false, the response is one body once the run is over.

string

completed or failed.

string

The whole reply. On a failed run, whatever text arrived before it failed.

array

The tool calls, tool results and steps, in order, as events. Text deltas are left out, because result holds them whole.

object

Present only when status is failed: { "code": "...", "message": "..." }.

string

Your sessionId, echoed unchanged, or the one generated for you.

string

The agent that answered.

number

The version that answered, as shown on the agent’s Versions tab.

string

This request’s ID, starting req_. Quote it to support.

number

How long your agent took, in milliseconds.

For the echo agent from the quickstart:

Terminal

curl https://api.onecortex.io/v1/agents/agt_.../invoke \
  -H "Authorization: Bearer $ONECORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"hello"}'

Response

{
  "status": "completed",
  "result": "You said: hello",
  "events": [
    { "v": 1, "type": "tool_call_start", "id": "call_1", "name": "word_count" },
    { "v": 1, "type": "tool_call_args", "id": "call_1", "delta": "{\"text\": \"hello\"}" },
    { "v": 1, "type": "tool_call_end", "id": "call_1" },
    { "v": 1, "type": "tool_result", "id": "call_1", "output": "1" }
  ],
  "sessionId": "01K...",
  "agentId": "agt_...",
  "versionNumber": 1,
  "requestId": "req_01K...",
  "durationMs": 212
}

When your agent raises

If your agent’s own code raises, the run fails, and the response is 502 with the same body: status is failed, result holds any text sent before the failure, and error names the exception. Your traceback is not in the response. It is in your agent’s logs.

Response (502)

{
  "status": "failed",
  "result": "",
  "error": { "code": "agent_error", "message": "ValueError: the agent was asked to raise" },
  "events": [],
  "sessionId": "01K...",
  "agentId": "agt_...",
  "versionNumber": 1,
  "requestId": "req_01K...",
  "durationMs": 31
}

The event stream

With stream true, the response is text/event-stream. Each event is one frame: an event: line naming its type, a data: line holding the event as JSON on a single line, and a blank line.

Stream

event: text
data: {"v":1,"type":"text","delta":"You said: hello"}

event: done
data: {"v":1,"type":"done","result":"You said: hello","sessionId":"01K...","versionNumber":1,"durationMs":212}

Exactly one terminal event ends every stream: done or error. Nothing follows it.
done carries the whole reply in result, plus sessionId, versionNumber and durationMs.
While your agent is working and has nothing to send, Onecortex writes a comment line, : ping, every 15 seconds, so no proxy closes an idle connection. Server sent event clients ignore comments.

Every event type and its fields are on Streaming and events.

A stream that has started has already sent 200 OK, and cannot change it. If the run fails after that, the failure arrives in the stream as event: error. Handle it: a client that reads only text and done shows a failed run as an empty success.

Stream that fails

event: error
data: {"v":1,"type":"error","code":"agent_error","message":"ValueError: the agent was asked to raise"}

Response headers

Header	On	Holds
`X-Request-Id`	Every response	The request ID, `req_...`, also in every error body
`X-Onecortex-Session-Id`	Every response that reached your agent	The session ID, so a caller that sent none can continue the conversation
`X-RateLimit-Remaining`	Every response that reached your agent	Requests left in your organization’s burst allowance
`Retry-After`	`429`	Whole seconds to wait before trying again

Errors

An error before the run starts is an HTTP status with this body:

{
  "error": {
    "code": "not_found",
    "message": "That agent does not exist.",
    "requestId": "req_01K..."
  }
}

Status	`code`	Message	Retry
400	`invalid_request`	`Request must include a 'prompt' field.`	No, fix the request
400	`invalid_request`	`The request body must be valid JSON.`	No, fix the request
400	`validation_failed`	Names the field, for example the 4 KB `metadata` limit	No, fix the request
401	`unauthenticated`	`A valid Onecortex API key is required.`	No, check the key
403	`organization_suspended`	`This organization is suspended. Contact Onecortex support.`	No
404	`not_found`	`That agent does not exist.`	No, check the ID and the key’s scope
409	`agent_not_ready`	`This agent has not finished its first deployment yet.`	Yes, once the first build succeeds
409	`agent_not_deployed`	`This agent has no deployed version. Its first deployment did not succeed.`	No, fix the build and deploy
410	`agent_deleted`	`This agent has been deleted.`	No
413	`payload_too_large`	`The request body can be at most 1 MB.`	No
429	`rate_limited`	`Too many requests. Try again in <n> seconds.`	Yes, after `Retry-After`
502	`agent_error`	Your agent’s exception, as `<Type>: <message>`	Only if your code would succeed next time
502	`upstream_error`	`The agent could not be reached. Try again.`	Yes
503	`agent_unavailable`	`This agent is not available right now. Try again.`	Yes
503	`service_unavailable`	`Onecortex is temporarily unavailable. Try again.`	Yes
503	`capacity_exceeded`	`Onecortex is at capacity in this region.`	Yes, later

An agent still serves while a new version builds, and while a new version’s build has failed: a deploy never takes a working agent offline. Every error, with its cause and fix, is on Errors.

Limits

60 requests a minute per organization with a burst of 20, 30 a minute per agent, and 10 streams open at once per organization. A request body is at most 1 MB and metadata at most 4 KB. All limits are on Limits.

Examples in your language

Python

httpx, streamed.

TypeScript

fetch, with the stream reader.

curl

curl -N, from a terminal.

Get started

Build your agent

Frameworks

Deploy

Call your agent

Observe

Production

Organizations

Resources

The endpoint

Authentication

The request

The JSON response

When your agent raises

The event stream

Response headers

Errors

Limits

Examples in your language

Python

TypeScript

curl

​The endpoint

​Authentication

​The request

​The JSON response

​When your agent raises

​The event stream

​Response headers

​Errors

​Limits

​Examples in your language

Python

TypeScript

curl

The endpoint

Authentication

The request

The JSON response

When your agent raises

The event stream

Response headers

Errors

Limits

Examples in your language