Runtime API — getting started

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.