Runtime API — getting started

Availability: All plans. Requires a deployed agent and an agent token.

Every agent you build in Agentman Studio is also an API. The Runtime API (v3) lets you call your agent from your own backend, app, or website — streaming responses in native LangChain format, uploading files for the agent to read, and inspecting the agent's model and capabilities.

Base URL

https://api.agentman.ai

All v3 endpoints live under this host. Responses are JSON, except the streaming endpoint (Server-Sent Events) and file downloads (raw bytes).

Authentication

Every request is authenticated with an agent token — a signed JWT scoped to one agent, its application, and your tenant. You get one when you deploy an agent in Studio, or by calling the Studio API:

POST https://studio-api.agentman.ai/v2/studio/agents/{agent_id}/tokens

(with your Studio login; the request takes tenant_id, application_id, and optional allowed_domains, permissions, and expiry_hours).

Send the token on every Runtime API call, preferably as a Bearer header:

Authorization: Bearer <AGENT_TOKEN>

Also accepted: an X-Agent-Token header or a ?token= query parameter. If the token was minted with allowed_domains, browser requests must originate from one of those domains — the Origin header is checked against the list, and CORS is granted per-token, so you never need a manual domain whitelist.

Treat agent tokens like API keys: they grant execute_agent on that agent for as long as they're valid, so keep them server-side unless you deliberately created a domain-bound token for browser use.

Your first request

Stream a message to your agent:

curl -N -X POST https://api.agentman.ai/v3/agent/stream \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "Hello! What can you help me with?",
    "conversation_id": "3f6f9f0a-8f5e-4a4a-9d5b-1c2d3e4f5a6b"
  }'

The -N flag disables curl buffering so you see events as they arrive. You'll get a stream of data: {...} events ending in a stream_complete event. See Call your agent (streaming) for the full event reference.

Always generate and send your own conversation_id (any stable string; a UUID is conventional). Reusing the same ID continues the conversation — the agent loads its own history server-side, so you never resend past messages.

The v3 endpoints

Endpoint	What it does
`POST /v3/agent/stream`	Stream agent responses (SSE, native LangChain format)
`GET /v3/agent/info`	Agent configuration, model, and capabilities in one call
`GET /v3/agent/models`	All available models with capability metadata
`GET /v3/agent/capabilities`	Just the multimodal capabilities (images, audio, docs…)
`POST /v3/files/upload`	Upload a file for the agent to use
`GET /v3/files`	List your uploaded files
`GET /v3/files/{file_id}`	File metadata + LLM-compatibility check
`GET /v3/files/{file_id}/download`	Download the file bytes
`POST /v3/files/{file_id}/url`	Mint a fresh presigned URL
`GET /v3/files/validate/{file_id}`	End-to-end accessibility + compatibility check

Limits and errors

File uploads: 50 MB per file, common document/image/text types (see the Files API).
Streaming: the server keeps the connection alive with heartbeats; if the model produces no event for 5 minutes, the stream ends with a timeout error event.
Errors outside a stream are standard HTTP status codes with a JSON detail field: 401 (missing/invalid token), 403 (token doesn't match the agent's tenant, or Origin not allowed), 400 (validation), 500 (server error). Errors inside a stream arrive as error events on the stream itself.

Availability

All plans. Requires a deployed agent and an agent token.