Docs

Recipes

1. A support agent with a connector

Describe the agent with the connector it needs named explicitly — e.g. "a support agent that can look up open tickets in our Notion database and answer questions about them." The builder grants the notion connector automatically if you mention it; otherwise add it from the agent's Tools tab. Configure the connector's credentials once under Settings → Connectors — instructions and a sample value are shown for whichever connector you pick.

2. A multi-step research workflow

For anything beyond one call-and-respond — loop until a quality bar is met, branch based on what a step actually returned — open the agent's Graph tab. Add an agent node for each LLM step, a tool node for anything that calls out, and a router node to decide what happens next from the real output, not a fixed order. Every step shares one state object and the whole run is traced as a single unit, the same as a simple agent.

3. Calling an agent from your own backend

Generate a platform API key under Settings → API keys, then POST to the agent's chat endpoint:

curl -s https://api.yan-tra.com/provision/agents/{agent_id}/chat \
  -H "Authorization: Bearer yk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "What'\''s the status of order #4821?"}'

The agent needs the rest channel bound before an API-key caller can reach it — add it from the agent's Channels tab if it isn't already there.

API reference

Authentication

Every request needs Authorization: Bearer yk_live_.... A platform API key is either tenant-wide (usable against any of your deployed agents with the rest channel bound) or scoped to one specific agent at creation time. Keys are shown once, at creation — only a hash is stored server-side, so there's no way to retrieve a lost key; revoke it and create a new one.

Base URL

https://api.yan-tra.com

Send a message to an agent

POST /provision/agents/{agent_id}/chat

{
  "text": "your message",
  "end_user_id": "stu_8F21"      // optional: your own id for the person you're calling on behalf of
}

→ 200 OK
{
  "trigger_id": "trig_...",
  "status": "done",
  "response": "...",
  "error": null,
  "ai_generated": true,
  "disclosure_shown": false
}

Pass end_user_id whenever the message comes from one of your own users. It gives that person their own conversation history and memory with the agent, and it's how the agent finds their documents in the document vault.

Document vault

Upload files your users have shared with you (a CV, a transcript) or documents for everyone (a brochure, a policy), and agents with the document_vault connector can read them. Requires the Team plan. Use a tenant-wide API key: keys scoped to one agent can't use the vault.

• Set owner_identity to the same id you send as end_user_id in chat. Leave it out for a document every user can see.
• An agent only ever sees the calling user's own documents plus shared ones. Who the user is comes from your end_user_id, never from the conversation. Website-widget visitors and console test chats see shared documents only.
• Agents read text. PDFs are read through their text layer, and plain-text files as they are. Scanned PDFs and images have no text, so the upload returns "has_text": false; upload your own OCR text as a .txt file alongside it.
• There's no update call. To replace a file, delete the old one and upload the new one, or the agent will see both.

Upload a document

POST /tenant/vault/documents

{
  "filename": "cv.pdf",
  "content_type": "application/pdf",
  "content_base64": "JVBERi0xLjQK...",   // file bytes, base64; max 10 MB before encoding
  "owner_identity": "stu_8F21"           // optional; omit for a shared document
}

→ 200 OK
{
  "id": "4f0c2a7e-...",
  "filename": "cv.pdf",
  "content_type": "application/pdf",
  "size_bytes": 182344,
  "owner_identity": "stu_8F21",
  "created_at": "2026-10-04T10:21:46+00:00",
  "has_text": true
}

List documents

GET /tenant/vault/documents                          // all documents
GET /tenant/vault/documents?owner_identity=stu_8F21  // one user's documents
GET /tenant/vault/documents?shared=true              // shared documents only

→ 200 OK
[ { "id": "...", "filename": "cv.pdf", "content_type": "application/pdf", "size_bytes": 182344,
    "owner_identity": "stu_8F21", "created_at": "...", "has_text": true } ]

Newest first, up to 200 documents.

Read a document's text

GET /tenant/vault/documents/{document_id}/text

→ 200 OK
{ "id": "...", "filename": "cv.pdf", "text": "..." }

Exactly what an agent reads, which makes it the quickest check that an upload worked.

Delete a document

DELETE /tenant/vault/documents/{document_id}

→ 200 OK
{ "deleted": true }

Works on every plan, so you can still remove documents after a downgrade.

Errors

• 401 — missing or invalid API key.
• 402 — a plan limit was reached (monthly call allowance or, on the pooled runtime, the platform budget cap), or the feature needs a higher plan (the document vault needs Team). The response names which one.
• 403 — the agent doesn't have the channel this call needs bound, an agent-scoped key was used against a different agent, or an agent-scoped key was used on the document vault.
• 404 — no agent or document with that id.
• 413 — a vault upload is larger than 10 MB.
• 422 — the request body is malformed, e.g. content_base64 isn't valid base64.

Rate limits

There's no separate per-second rate limit today. Usage is measured against your plan's monthly call allowance, shown under Settings → Billing; calls beyond it are billed as add-on packs rather than refused, unless your organisation has a hard limit set.

Retention & audit

Every run — chat, scheduled, or API-triggered — is captured as a trace: the prompt, every tool call and its result, tokens used, cost, and latency, tied to one trigger_id. You can see it in the console under an agent's Traces tab.

How long a trace is kept is a plan setting, not a policy document — Free keeps 7 days, Pro and the trial 90, Team 13 months, Enterprise is configurable with legal-hold support. A scheduled job enforces this on both the metered usage record and the trace itself; a trace past its window is inaccessible via the console and the API alike, independent of whether the purge has physically run yet.

Where an agent's compliance profile requires it, EU AI Act Article 50 disclosure — telling the end user they're talking to an AI — is applied automatically and recorded per response, not left to the agent's own prompt.

A public, real example trace — the actual proof of all of this — is planned here but not live yet: publishing one safely needs a dedicated, narrowly-scoped read endpoint and a check that nothing sensitive ends up in it, rather than just turning on public access to trace data. Once that's built, it'll be linked from here.