Can I list or read AskVault conversations through the API?

Not today. The public v1 API has no endpoint that lists conversations or returns a conversation's message history. Use the dashboard Inbox, or Export all (CSV) on Growth and above.

Can I update or delete an AskVault conversation via API?

There is no PATCH or DELETE endpoint for conversations. The v1 API can hand a conversation to a human, record a CSAT rating, and record whether the customer's issue was resolved.

How do I export all AskVault conversations?

On Growth and above, click Export all (CSV) in the Inbox. It downloads every message in the workspace as one CSV file. It is a dashboard feature, not an API endpoint.

Conversations and the AskVault API, what exists today

Written by Joseph Russo, Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan

Last updated: October 18, 2026 · 4 min read

What the v1 API offers

The public REST API has eight endpoints under https://api.askvault.co/v1.

Every endpoint except /v1/health needs Authorization: Bearer ak_xxx; see authentication. The key identifies the workspace, so no request carries a workspace_id.

Endpoint	What it does
`GET /v1/health`	Liveness check. No key needed.
`POST /v1/query`	Ask a question, get a grounded answer. See POST /v1/query.
`POST /v1/query/stream`	The same answer, streamed. See POST /v1/query/stream.
`POST /v1/agent/ask`	Ask, and also get confidence and handoff signals back.
`POST /v1/agent/escalate`	Hand a conversation to a human in your Inbox.
`POST /v1/agent/csat`	Record a 1 to 5 satisfaction rating for a conversation.
`POST /v1/agent/resolve`	Record whether the customer says their issue is resolved.
`GET /v1/agent/capabilities`	List the workspace's enabled skills and connected channels.

There is no /v1/conversations endpoint of any kind: no list, no fetch, no message history, no internal notes, no search, no update and no delete.

How conversations show up in the API

Two endpoints create and continue conversations.

POST /v1/query and POST /v1/agent/ask both return a conversation_id. Send it back on the next call to keep the same thread, or send your own session_id per end user. The conversation then appears in your dashboard Inbox like any other channel.

POST /v1/agent/ask body:

Field	Type	Notes
`message`	string	Required. 1 to 8,000 characters.
`session_id`	string	Optional. Your per-end-user thread key.
`conversation_id`	string	Optional. Continue an existing conversation.
`user`	object	Optional. `external_id`, `email`, `name`, `plan`.
`top_k`	integer	Optional. 1 to 20.

curl -X POST https://api.askvault.co/v1/agent/ask \
-H "Authorization: Bearer ak_xxx" \
-H "Content-Type: application/json" \
-d '{"message": "Where is my order?", "session_id": "user_123"}'

import requests
r = requests.post(
  "https://api.askvault.co/v1/agent/ask",
  headers={"Authorization": "Bearer ak_xxx"},
  json={"message": "Where is my order?", "session_id": "user_123"},
)
print(r.json())

const r = await fetch("https://api.askvault.co/v1/agent/ask", {
method: "POST",
headers: { "Authorization": "Bearer ak_xxx", "Content-Type": "application/json" },
body: JSON.stringify({ message: "Where is my order?", session_id: "user_123" }),
});
console.log(await r.json());

Response:

{
  "answer": "Your order ships within 2 business days...",
  "sources": [
    { "document_name": "Shipping policy", "url": "https://example.com/shipping", "relevance_score": 0.82 }
  ],
  "confidence": 0.91,
  "answered": true,
  "escalated": false,
  "conversation_id": "c0a8...",
  "message_id": "9f1e...",
  "tokens_used": 187
}

escalated is true when the conversation has been handed to a human. confidence and answered can be null when they could not be read for that turn.

Act on a conversation

Three endpoints take a conversation_id from your own workspace.

An ID from another workspace returns 404 Conversation not found.

Hand off to a human. POST /v1/agent/escalate with {"conversation_id": "...", "reason": "..."} (reason optional, up to 500 characters). Returns {"conversation_id", "status": "escalated", "escalated": true}.

Record CSAT. POST /v1/agent/csat with {"conversation_id": "...", "score": 4, "comment": "..."}. score is 1 to 5; comment is optional, up to 2,000 characters. Returns {"conversation_id", "csat_score"}. A 409 means a rating is already recorded for that conversation.

Record a resolution. POST /v1/agent/resolve with {"conversation_id": "...", "resolved": true}. true records the conversation as confirmed resolved; false hands it to a human. Returns {"conversation_id", "resolution_state"}, where resolution_state is confirmed or escalated.

Responses can gain new fields over time. Ignore fields you don't recognise.

Getting conversation history out

There is no API for this today. Your options:

Inbox. Read any conversation in the dashboard Live Chat inbox.
Export all (CSV). Growth+ In the Inbox, click Export all (CSV). It downloads every message in the workspace as one CSV: timestamp, conversation ID, session ID, role, content, channel, tokens used and feedback. It ignores the filters you have applied. This is a signed-in dashboard feature; API keys can't call it.
Webhooks. To receive conversation events as they happen, use webhooks.

Common pitfalls

Looking for a list endpoint. There isn't one. Store the conversation_id your own calls return if you need to refer to those conversations later.

Using an API key on dashboard URLs. Routes under /api/workspaces/... take a signed-in dashboard session, not an ak_ key. Only /v1 routes (and the workspace MCP server) accept API keys.

Sending a conversation ID from another workspace. Each key is bound to one workspace. A conversation from a different workspace returns 404.

FAQ

Can I list or read conversations via API?

Not today. Use the Inbox, or Export all (CSV) on Growth and above.

Can I update or delete a conversation via API?

No. There is no PATCH or DELETE conversation endpoint. The v1 API can escalate, rate and resolve a conversation, as described above.

How long are conversations retained?

Retention scales with plan: 7 days on Free, 30 days on Starter, 90 days on Growth, and 365 days on Business and Enterprise. Older conversations are deleted automatically.

Was this page helpful?