Developer docs

Conversations, usage and approvals

Read-only routes for looking back at what your agents did and how much of your plan is left. They return your own account’s data only.

Routes

Read routes
Route	Returns
`GET /v1/conversations`	Your conversations, newest first.
`GET /v1/conversations/{id}`	One conversation: transcript, every tool call, approvals and hand-offs.
`GET /v1/conversations/{id}/messages`	The transcript only.
`GET /v1/usage`	Messages used and remaining for each agent, and the last 30 days.
`GET /v1/subscriptions`	Your subscriptions with period, usage and any scheduled cancellation.
`GET /v1/approvals`	Actions waiting for a person. Optional `?status=`.
`GET /v1/handoffs`	Conversations the agent handed over to your staff.
`GET /v1/catalogue`	Public: the agents, their tools and plans. No key needed.

List conversations

Filter with ?channel= (api, widget, whatsapp or email). Up to 100 come back per call; for older ones pass ?before= with the updated_at time of the last row you have.

List conversations (curl)curl "https://api.safecoin.online/v1/conversations?channel=api" \
  -H "Authorization: Bearer $HAVEN_API_KEY"

Each row has id, agent_id, title, channel, message_count, created_at, updated_at, pending_approvals and open_handoff.

Read one conversation

GET /v1/conversations/{id} returns conversation, messages (role, text, tools, createdAt), toolCalls (the audit record of everything the agent did), approvals and handoffs. An unknown id, or one that belongs to someone else, gives 404 conversation_not_found.

Usage

curl

Check usage (curl)curl https://api.safecoin.online/v1/usage -H "Authorization: Bearer $HAVEN_API_KEY"

You get agents, one entry per subscribed agent (agentId, agentName, planName, status, periodStart, periodEnd, used, cap, remaining), and last30Days with messagesPerDay and tokens. Unused messages do not roll over to the next period.

Approvals

Actions with real consequences (a refund, for example) are never done by the agent alone. The agent records a request and tells the customer a person will confirm. You can list pending requests with a key, but approving or rejecting is for a logged-in owner or admin in the dashboard; a key gets 403 session_required. The decision is recorded under that person’s email.

A request that is already decided returns 409 not_pending.
The approvalId in a chat reply matches the id in this list.