Assist API

​

How a call reaches the visitor

1. Your server calls POST /api/v1/assist with the tool, the text and the person.
2. Puntego queues the call for that person. While the guide is loaded on a page they have open and visible, the page checks for a waiting call every few seconds (about 4 s), only when the owner’s agent switches are on, the visitor’s consent allows the assistant where your consent settings ask for it, and the workspace holds a live key with assist:invoke.
3. The page picks the call up and runs it as an agent turn: the guide answers, points, runs a tour or shows the action card, in front of the person.
4. The page reports what happened, and the API returns it.

​

Start the guide

curl -X POST https://worker.puntego.com/api/v1/assist \
  -H "Authorization: Bearer pk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4821-step-2" \
  -d '{
    "tool": "show_me",
    "text": "Where do I add a teammate?",
    "customer_id": "user_8412"
  }'

{
  "object": "assist_invocation",
  "id": "asi-4f8b2c1e-9a0d-4e6b-8c1f-2d3e4f5a6b7c",
  "tool": "show_me",
  "type": "started",
  "state": "completed",
  "status": "shown",
  "summary": "The person now sees a 3-step tour on the page “Invite a teammate”.",
  "answer": "Open Settings → Team, then press Invite.",
  "sources": [{ "title": "Inviting teammates", "href": "https://example.com/docs/team" }],
  "follow_ups": ["Can I change a teammate's role later?"],
  "shown": { "kind": "tour", "steps": 3, "title": "Invite a teammate" },
  "receipt": null,
  "error": null,
  "created_at": "2026-10-13T10:00:00.000Z",
  "claimed_at": "2026-10-13T10:00:03.120Z",
  "completed_at": "2026-10-13T10:00:07.480Z",
  "expires_at": "2026-10-13T10:00:15.000Z"
}

curl https://worker.puntego.com/api/v1/assist/asi-4f8b2c1e-9a0d-4e6b-8c1f-2d3e4f5a6b7c \
  -H "Authorization: Bearer pk_live_your_key"

​

What stays governed

• Writes wait for the visitor. Only do_action can lead to a write, and the visitor approves it on the guide’s card, with the line “An AI agent asked for this. Nothing changes unless you approve it here.” Your server can never approve anything.
• Payments, signatures and deletions are always refused for an agent: not_done with error.code: "high_risk_refused", and the guide offers the person “Show me”.
• The same switches and consent. Each tool needs its switch in Settings → Guide behavior → Other AI agents, and a visitor who has not consented where your settings ask for it never picks a call up.
• Metered like visitor questions. Each call that runs is one AI reply on your monthly meter, like any agent turn; a write counts against the plan’s actions. A call that never runs costs nothing: one no page picked up (no_live_session), one refused before anything was queued, or one the page could not take (type: "unavailable").
• Audit log. Each call that runs appears in Audit log as Other AI agent, like an in-browser call.

​

Limits and retention

• 60 calls a minute per key (assist/key-rate-limited, 429 with Retry-After).
• Per visitor session, as for every agent call: at most 10 agent calls a minute and 120 an hour. A call over that limit ends with type: "unavailable" and status: "rate_limited".
• At most 3 calls wait for one person at once (too_many_pending).
• Calls are kept for seven days. The request text is kept only until a page picks the call up (or it expires); from then on it lives in the conversation, under your transcript retention, like any visitor question.
• Deleting a customer deletes their calls: those addressed to their customer_id, and those a page signed in as them picked up, whatever visitor_id they were addressed to.

​

Errors and unavailable codes

​

Next steps

• Other AI agents for the in-browser tools and the typed response.
• Workspace MCP server to read analytics, conversations and the Inbox from Claude or Cursor.
• Authentication for API keys and scopes.