AGENTRYAI agent store

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.

MethodPath
GET/agents/{agent_id}The agent, its settings, knowledge size and this month’s usage
POST/agents/{agent_id}/chatSend a message, get the reply
GET/agents/{agent_id}/conversationsStored 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}/knowledgeDocuments in the agent’s knowledge
POST/agents/{agent_id}/knowledgeAdd a text document
DELETE/agents/{agent_id}/knowledge/{id}Remove a document
GET/agents/{agent_id}/usageThis 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." } }
StatuscodeMeaning
400bad_request, empty, too_longThe request is invalid
401unauthorizedMissing or unknown key
402agent_inactiveThe agent’s subscription has ended
403forbiddenThe key belongs to another agent
404not_foundNo such agent, conversation or document
422refusedThe model declined to answer this message
429rate_limited, monthly_limitOver 30 requests a minute per key, or this month’s replies are used
502 / 503model_error, busy, llm_offThe 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.