API reference
Call your agent over REST
Every owned agent has its own endpoint and keys. Send a message, get a reply, keep the conversation going. JSON in, JSON out.
Authentication
Create a key in Studio → your agent → API. Send it as a Bearer token. A key works only for its own agent.
Authorization: Bearer agk_…
Keys are for servers. Never ship them in a website or a mobile app: call the API from your backend and pass the reply on.
| Method | Path | |
|---|---|---|
GET | /agents/{agent_id} | The agent, its settings, knowledge size and this month’s usage |
POST | /agents/{agent_id}/chat | Send a message, get the reply |
GET | /agents/{agent_id}/conversations | Stored conversations, most recent first |
GET | /agents/{agent_id}/conversations/{id} | One conversation with its messages |
DELETE | /agents/{agent_id}/conversations/{id} | Delete a conversation |
GET | /agents/{agent_id}/knowledge | Documents in the agent’s knowledge |
POST | /agents/{agent_id}/knowledge | Add a text document |
DELETE | /agents/{agent_id}/knowledge/{id} | Remove a document |
GET | /agents/{agent_id}/usage | This month’s replies |
Base URL: https://agentry.life/api/v1
Chat
POST /agents/{agent_id}/chat with message (up to 4000 characters). Without conversation_id a new conversation starts; send the returned conversation_id with the next message to continue it. user is your own id for the end user, stored with the conversation.
curl https://agentry.life/api/v1/agents/agt_…/chat \
-H "Authorization: Bearer agk_…" \
-H "Content-Type: application/json" \
-d '{"message": "Do you ship to Portugal?", "user": "customer-42"}'
{
"id": "msg_…",
"object": "chat.reply",
"agent_id": "agt_…",
"conversation_id": "conv_…",
"reply": "Yes: EU delivery takes 4–7 working days and costs 9.90 EUR.",
"model": "claude-opus-5-5",
"truncated": false,
"created_at": "2026-11-18T10:00:00.000Z",
"usage": { "input_tokens": 1830, "output_tokens": 64, "replies_used": 12, "replies_limit": 600 }
}
The agent uses the setup and knowledge you saved in the studio at the moment of the request. Each successful reply counts as one of the agent’s monthly replies; failed ones don’t.
Streaming
Add "stream": true to get server-sent events: delta events with pieces of text as they are written, then one done event with the same object as above. On failure you get an error event instead.
event: delta
data: {"text":"Yes: EU delivery"}
event: delta
data: {"text":" takes 4–7 working days"}
event: done
data: {"id":"msg_…","reply":"Yes: EU delivery takes 4–7 working days and costs 9.90 EUR.", …}
Use the reply of the done event as the final text: in rare cases a draft is replaced before it is finished.
Keeping the history yourself
If your app already stores the conversation, send the earlier turns in messages and leave out conversation_id. Nothing is stored on our side and conversation_id in the reply is null.
{
"message": "And the price?",
"messages": [
{ "role": "user", "content": "Which backpack fits a 15-inch laptop?" },
{ "role": "assistant", "content": "The Summit 28: it has a padded sleeve for laptops up to 15.6 inch." }
]
}
Conversations
GET /agents/{agent_id}/conversations lists the latest 100; GET …/conversations/{id} returns the messages; DELETE removes one. Conversations are kept for 12 months after their last message.
Knowledge
Keep the agent’s knowledge in sync with your systems, for example a product feed every night: delete the old document, add the new one.
curl https://agentry.life/api/v1/agents/agt_…/knowledge \
-H "Authorization: Bearer agk_…" \
-H "Content-Type: application/json" \
-d '{"title": "Product feed", "source": "feed.csv", "content": "name,price_eur,stock\nSummit 28 backpack,65,12\n…"}'
Up to 300,000 characters per document, 100 documents and 1,500,000 characters per agent. With source ending in .csv the header row is repeated in every passage the agent reads; .html is reduced to text. Knowledge up to 60,000 characters is read whole for every reply; above that, the agent gets the 8 passages most relevant to each message.
Errors and limits
{ "error": { "code": "monthly_limit", "message": "This agent has used this month’s replies." } }
| Status | code | Meaning |
|---|---|---|
| 400 | bad_request, empty, too_long | The request is invalid |
| 401 | unauthorized | Missing or unknown key |
| 402 | agent_inactive | The agent’s subscription has ended |
| 403 | forbidden | The key belongs to another agent |
| 404 | not_found | No such agent, conversation or document |
| 422 | refused | The model declined to answer this message |
| 429 | rate_limited, monthly_limit | Over 30 requests a minute per key, or this month’s replies are used |
| 502 / 503 | model_error, busy, llm_off | The model failed or is unavailable. The reply is not counted; retry later |
Replies can take several seconds; use a client timeout of at least 120 seconds. Responses carry the header AI-Disclosure: tell your users they are talking to an AI.