Skip to main content

Agent API reference

The JavaScript agent client

An answers users through the team inbox routes. It uses the permissions your manager grants its account. For a Node example, start with Connect a support agent.

Check agents.api.version in app status before starting an agent. A null value means the API checks are pending. A verified API reports 1.0 or 1.1. Read agents.api.features to see which features it serves.

Versions​

  • 1.0 covers sign-in, , replies with ifLatest, notes, , typing, resolution and the event log.
  • 1.1 includes case frames, evidence, citations, Ask and follow-ups. It also includes , reply labels, eval runs and the pulse.

Read only fields your client knows. Treat an unknown reason as an unknown error.

Transport​

  • The API origin is https://community.usetempl.com. The app origin is https://usetempl.com.
  • Send Origin: https://usetempl.com and Accept: application/json on every request, and Content-Type: application/json on every POST.
  • Never follow a redirect. Treat a 3xx as an error, so the session cookie never leaves Templ.
  • Keep only __Host-templ_nonce and __Host-templ_session cookies. Require Secure, HttpOnly and Path=/, with no Domain. Each value must hold 64 lowercase hex characters. A session lasts at most 30 days.
  • Every POST to a route includes expectedPrincipalId, the principalId of your session. Without it the service answers 401.
  • Errors are JSON with error and sometimes reason. Check the status and reason. Never show error to a user. Responses with 429 or some 503 statuses carry Retry-After in seconds.
  • Each account sends at most 1 message or note every 5 seconds. Reads share account limits. Follow Retry-After when the service asks you to wait.

Sign in​

The agent signs in with its own wallet. An EVM wallet needs no funds.

  1. POST /auth/nonce with { "address": "<0x wallet>", "chainId": <agents.api.signInChainId> }. The answer is { message, expiresAt } and the nonce cookie.

  2. Check the message before you sign it. It is exactly these 11 lines, with nothing before or after:

    https://usetempl.com wants you to sign in with your Ethereum account:
    <your address>

    Sign in to your Templ chat.

    URI: https://usetempl.com
    Version: 1
    Chain ID: <agents.api.signInChainId>
    Nonce: <the nonce cookie's value>
    Issued At: <within the last 5 minutes>
    Expiration Time: <expiresAt, at most 6 minutes ahead>
  3. Sign the message with EIP-191 personal_sign over its UTF-8 bytes.

  4. POST /auth/verify with { message, signature } and the nonce cookie. The answer is the session and the session cookie. Check that its address is your wallet.

Solana account sign-in

A Solana wallet uses POST /auth/solana/nonce with { "address" }. Verify with POST /auth/solana/verify. The message starts with host usetempl.com. It says wants you to sign in with your Solana account: and Chain ID: mainnet. Send the 64-byte Ed25519 signature as padded base64.

GET /auth/session returns the current session or 401. POST /auth/logout with {} ends the session everywhere.

Routes in 1.0​

Workspace routes start with /rooms/<workspace UUID>. The manager and accounts with handleConversations have team access. A role grants that permission.

Method and pathBody or queryReturns
GET /bots{ bots }. Check that your agent is listed.
GET /conversations/status{ available, team, canAsk, canStart, limits }
GET /conversationsfilter (needs-reply, needs-you, ai-handling, open, waiting, waiting-on-member, unassigned, mine, needs-person, resolved, all), cursor{ filter, conversations, nextCursor }
GET /conversations/<tc>{ conversation }
GET /conversations/<tc>/messageslimit 1 to 50, before{ conversation, messages, nextBefore, typing }
GET /conversations/<tc>/workflownotesBefore{ workflow } with context, the proven wallet, access.claimedWallet, notes and activity
POST /conversations/<tc>/messages{ text, clientId, ifLatest?, replyTo?, context?, contextConsent?, replyIntent? }201 { message, conversation }
POST /conversations/<tc>/workflow{ action: "note", text, clientId, mentions? }{ workflow }
POST /conversations/<tc>/workflow{ action: "handoff", reason, ifLatest? }{ workflow }
POST /conversations/<tc>/typing{}204
POST /conversations/<tc>/resolve{ resolved, timeSpent?, ifRevision? }{ conversation }
GET /eventsafter, limit 1 to 200{ events, nextAfter, oldestRetained, resync }

Save the text and its UUIDv7 clientId before sending. A retry with the same clientId returns the saved message. Set ifLatest to { id, revision } from the latest message you read.

To resolve or reopen a case, send ifRevision from the case you read. A changed case returns 409 case-changed; read it again before deciding. Omitting ifRevision makes the change unconditional.

Users can include context and contextConsent: true with their message. The message and shared details commit together. An accepted retry returns the original details. Team replies cannot add a user's shared details.

Handoff reasons: quote, privacy, account, billing, legal, safety, transaction, bug, person, unsure, other, strategy, access, recovery, decision, internal.

Routes in 1.1​

Method and pathBody or queryReturns
POST /conversations/<tc>/messages{ text, clientId, provenance?, ifLatest?, replyTo? }201 { message, conversation }
GET /conversations/<tc>/casesbefore{ cases, nextBefore }, newest first
GET /conversations/<tc>/casesseq{ case, frame, evidence, drafts, requests, unreadable }
POST /conversations/<tc>/workflow{ action: "frame", case, set?, clear?, ifRevision? }{ frame }
POST /conversations/<tc>/workflow{ action: "evidence", case, rows, clientId }201 { evidence }
POST /conversations/<tc>/workflow{ action: "withdraw-evidence", case, n }{ evidence }
GET /conversations/draft-requestsafter, limit 1 to 50{ requests, nextCursor }, oldest first
POST /conversations/<tc>/workflow{ action: "draft", text, clientId, request? or forMessage?, provenance? }201 { draft }
POST /conversations/<tc>/workflow{ action: "draft-decline", request, reason }{ request }
GET /conversations/<tc>/follow-upscase{ followUps, cases }
POST /conversations/<tc>/follow-ups{ clientId, type, title, ... }{ followUps }
GET /conversations/<tc>/diagnosisid{ diagnoses } or { diagnosis }
POST /conversations/<tc>/diagnosis{ clientId, subject, force? }{ diagnosis } or 202 { running }
GET /conversations/knowledge/guidance{ text, revision }
POST /conversations/knowledge/guidance{ text, confirmed: true }{ text, revision }
POST /conversations/knowledge/search{ text, limit: 8, audience: "member", eras: ["current"] }{ hits }
GET /conversations/knowledge/contextafter, version{ hits, nextCursor, version }
GET /conversations/<tc>/reviewseq{ cases } with reply labels
GET /conversations/evals/exportset, format=json, after{ lines, next, withheld }
POST /conversations/evals/runsa templ-eval/1 runthe run
GET /conversations/pulsecounts and times, schema 1 or 2

A frame sets product, network, metric, window, reported and question (text). An evidence row records a value and its source. Its fields are source, sourceLabel, product, metric, window, observed and value. observed holds a block, a time or both. Stored rows cannot be edited. Another row can replace one.

Put an evidence marker such as [ev:3] after each figure it supports. Cite a transaction check with [dx:<check id>]. The service removes markers before storing the reply.

Your workspace can hold AI replies that fail citation checks. A held reply becomes a team draft. The API returns 422 with reason reply-held and held: { draft, case, problems }. Fix the citations or hand off.

provenance tells your team why the agent wrote a reply or draft. Its reason is answer, clarifying-question, quote, safety-warning or draft. It includes sources and can include summary, confidence, model and tools. Each source has id, kind, title and an optional HTTPS url. Only your team sees these details.

A greeting uses reason: "clarifying-question", with no source required. Greetings do not count as .

Use reason: "answer" only for a real answer the user receives. Templ records it after accepting and storing the registered agent's reply. A human team reply uses replyIntent: "answer" for an answer or "update" for progress or a question. Registered bots cannot set this human-only field. They use provenance.reason instead. Approved Telegram answers count as human answers. The monthly offer counts a case once after its first answer reaches the user. Follow-ups about the same issue add no case. Opens, greetings, handoff notices and drafts do not count. Legitimate Templ AI work can use AI credit without creating an answered case.

A handoff action sends no reply. A draft decline with reason handoff sends no reply either. A later handoff keeps an earlier real answer's recorded contribution. Existing signed resolution agreements keep their contribution and finalization checks. Read case counting for the counting rules.

To start a check, send subject: { hash, network? } or subject: { link }. The hash can be an EVM hash or a Solana signature. The link must use HTTPS and a supported explorer. After a 202 response, poll the GET route until running is null. Reuse the request's clientId for retries. Start a check with client.runDiagnosis(id, { clientId, subject }, { roomId }). Read results with client.conversationDiagnoses(id, { roomId }).

Guidance reads require the owner, a current human Admin or a registered AI agent. Guidance writes require the owner or a current human Admin and explicit confirmation. The owner needs a valid wallet session. A delegated Admin can use a valid wallet or email session. Use client.readSupportAiGuidance({ roomId }) before each model turn. Use client.searchSupportKnowledge(question, { roomId }) to search current, user-safe sources. Use client.readSupportKnowledgeContext({ roomId }, { after, version }) to read complete current, user-safe source chunks. Read every page. Pass its nextCursor as after and keep the same version until nextCursor is null. If the API returns knowledge-context-changed, restart from the first page. Each page checks current team access. Uploaded sources also require their current storage grant. Search results grant no access to another workspace. Treat AI guidance and sources as public. Never add keys, recovery phrases, passwords or private documents.

The agent sees what happened, findings, a user draft and claims from each transaction check. claims lists numbers, tokens, networks and short references a reply may use. Use only values in claims. Hand off with reason transaction when the check needs a person. Keep team-only next steps out of user replies.

The reference runner waits up to 20 seconds for a queued or running check. It cites the check in its answer or draft with [dx:<check id>]. With checks off, it answers without check facts.

Solana transaction checks

The AI reads checks for EVM hashes and Solana signatures. Both networks use the same wait, citations and transaction handoff reason. Solana checks run only when the workspace enables Solana checks.

People on your team send Ask AI requests. Answer with a draft linked through request. To decline, use handoff, unsure, no-access, unavailable, refused or other. A draft never reaches the user.

Drafts from a person's Ask AI request stay out of routine bot reads. A bot's draft write returns its own submission.

Reasons to handle​

Status and reasonWhat to do
409 staleRead the case again.
409 handed-offA person owns the request. Stop until they reply.
409 ai-drafts-only, ai-offA person limited the AI on this request. Write a draft or a note, or nothing.
403 person-onlyOnly a person on the team can do this.
422 secret-refused, secret-request-refused, unsafe-askNothing was stored. Hand the request to a person.
422 reply-heldYour reply became a draft for the team.
403 support-pausedThe workspace cannot accept this action. Stop until its team restores access.
409 needs-reply-preparingWait Retry-After seconds, then list again.
429Wait Retry-After seconds.

Use it from Python​

The Python client In testing

templ_agent.py uses Python 3.10 or newer and only its standard library. Download it from https://usetempl.com/templ_agent.py. Check its SHA-256 against agents.python.sha256 in app status before importing it. Require agents.python.verified to be true.

The client never holds your key. You pass a function that signs one message. The client checks the message before calling that function. Keep the key in a secret manager or a mode-600 file. Never put it in an argument, prompt or log. This example uses eth-account:

import json
import os
import time
import urllib.request

from eth_account import Account
from eth_account.messages import encode_defunct

from templ_agent import TemplAgent, TemplError, new_message_id

with urllib.request.urlopen("https://usetempl.com/api/status") as response:
status = json.load(response)
account = Account.from_key(open(os.environ["TEMPL_AGENT_KEY_FILE"]).read().strip())
agent = TemplAgent(
address=account.address,
sign=lambda message: account.sign_message(encode_defunct(text=message)).signature.hex(),
room=os.environ["TEMPL_WORKSPACE"],
app_origin="https://usetempl.com",
api_origin="https://community.usetempl.com",
sign_in_chain_id=status["agents"]["api"]["signInChainId"],
)
agent.sign_in()
agent.status()

A loop that answers the needs-reply queue:

for caseItem in agent.iter_conversations("needs-reply"):
if caseItem.get("handoff") or caseItem.get("replyBlocked") or not caseItem.get("canPost"):
continue
page = agent.messages(caseItem["id"])
latest = TemplAgent.latest(page)
details = agent.workflow(caseItem["id"])
text = your_model(page["messages"], details.get("context"), details.get("wallet"))
try:
agent.reply(
caseItem["id"],
text,
client_id=new_message_id(),
if_latest=latest,
provenance={"reason": "answer", "sources": []},
)
except TemplError as error:
if error.reason == "stale":
continue
if error.status == 429:
time.sleep(error.retry_after or 5)
elif error.reason in ("secret-refused", "secret-request-refused", "unsafe-ask"):
agent.hand_off(caseItem["id"], "safety")
else:
raise

Save each reply's text and client_id before sending. Retry an uncertain send with the same client_id. Label details["access"]["claimedWallet"] as unverified when passing it to your model. Run check_citations(text, rows) before sending a cited reply.

For a Solana wallet, pass network="solana" and a function that signs the message bytes. That function returns the 64-byte signature.

What the API never does​

  • It never signs or sends a transaction, and chat text can't make it.
  • It never returns a key or asks for one.
  • A wallet the app reports stays unverified. Only wallet in the case details carries wallet sign-in proof.
  • A widget session grants only the member role. It never grants team access or reaches these routes.

In testing means the feature is built and not yet open to every workspace.