Is there an official SDK for the AskVault API?

JavaScript and Python SDKs are on the roadmap. Until they ship, call the REST API directly from any language; the endpoints are documented in this reference.

Can I cache AskVault API responses in my application?

Yes, at your application layer. AskVault also keeps its own answer cache, which is cleared when your knowledge base changes. If your queries are stable, cache aggressively in your app.

Is there a sandbox for testing the AskVault API without affecting quotas?

The API requires a Starter plan or above: Free doesn't include API access. There's no separate sandbox mode; every successful query on a live key counts against your monthly message quota, so test with a low-traffic workspace.

How to use the AskVault REST API as a channel

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

Last updated: June 18, 2026 · 5 min read

What "API as a channel" actually means

The website widget, WhatsApp, Slack, and friends are pre-built integrations. The REST API is the same retrieval-augmented agent exposed as a single HTTP endpoint. You build whatever surface you want on top.

Three patterns where the REST API is the right channel:

Custom chat UI inside your product. You want full control over the look and behavior. The widget doesn't fit your brand or you need to integrate with internal authentication flows.
Backend automation. A nightly job that processes incoming customer emails, generates draft replies via AskVault, and stores them in your CRM.
Mobile app. Your iOS or Android app calls your own backend, which calls the AskVault API with a key kept on the server.

The pricing is the same per query as the other channels. You're not paying extra for the API; you're paying for the AI work the API performs.

Setup

Five minutes from zero to first API call.

Sign up for AskVault, then upgrade to Starter (or above). The REST API requires Starter or above: Free doesn't include API access.
Index some content. Run the onboarding wizard to crawl a website or upload a PDF. Pages become available to the API as they're indexed.
Generate an API key. Dashboard > Channels > REST API, then create a new key. Give it a name like "production-api". Copy the key (ak_xxx...) once; we only store the SHA-256 hash.
Send your first request. Example below. The key identifies the workspace, so the request body carries no workspace ID.

curl -X POST https://api.askvault.co/v1/query \
-H "Authorization: Bearer ak_xxx" \
-H "Content-Type: application/json" \
-d '{
  "query": "What is your refund policy?"
}'

import os, requests

response = requests.post(
  "https://api.askvault.co/v1/query",
  headers={"Authorization": f"Bearer {os.environ['ASKVAULT_API_KEY']}"},
  json={"query": "What is your refund policy?"},
  timeout=15,
)
print(response.json())

const response = await fetch("https://api.askvault.co/v1/query", {
method: "POST",
headers: {
  "Authorization": `Bearer ${process.env.ASKVAULT_API_KEY}`,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  query: "What is your refund policy?",
}),
});
console.log(await response.json());

You get back a JSON object with answer, sources, tokens_used, query_id, and conversation_id. The workspace comes from the API key, so you don't pass one. Full schema in the query endpoint reference.

Streaming responses with SSE

For low-perceived-latency UX (typing-effect chat), use the streaming endpoint at /v1/query/stream, which sends the answer as it is written.

const response = await fetch("https://api.askvault.co/v1/query/stream", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ASKVAULT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "How does pricing work?" }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

The streaming protocol is standard Server-Sent Events. Each chunk carries a token (partial answer text) or a status update; sources arrive in the final done: true frame. Full event reference is in the streaming guide.

Multi-user usage

If you're building a multi-tenant app where end users chat through your API integration, pass a unique session_id per end user (up to 200 characters):

{
  "query": "What's the status of my order?",
  "session_id": "your-app-user-id-42",
  "conversation_id": "conv-abc-123"
}

session_id keeps each end user's conversation on its own thread, so one user never sees another user's history. Pass session_id on every call: continuing a conversation by conversation_id is still rolling out, and until it is on for your workspace, calls without a session_id share one conversation. Rate limits are counted per API key, not per session_id: see rate limits.

Rate limits

Limits are per API key, not per plan. Every new key defaults to 60 requests/minute and 1,000/day. Support can raise either limit per key, up to 1,000/minute and 100,000/day; changing limits is not in the dashboard yet. The only plan requirement is Starter or above, since the API itself is a Starter+ feature.

When you exceed a limit you get HTTP 429 Too Many Requests with a message naming the limit. No rate-limit headers or Retry-After are sent. Full rate-limit reference at the rate-limits page.

Webhooks (incoming events)

In addition to the request/response pattern, you can subscribe to webhooks for events. AskVault POSTs to your endpoint when:

conversation.started: a new conversation begins on any channel
conversation.escalated: the bot escalates to a human
lead.captured: the collect_lead skill captures a lead
knowledge.gap_detected: a question your agent couldn't answer keeps recurring and auto-train recorded it as a new knowledge-gap suggestion (fires only when auto-train is on for the workspace)

Configure webhooks under Settings > Webhooks > Add Endpoint. Useful for piping AskVault events into your CRM, alert system, or analytics pipeline.

Security

Three things to keep in mind:

API keys are passwords. Store in environment variables, not source code. Rotate every quarter. If a key leaks, revoke it immediately in the dashboard.
Never call the API from a browser with your key. It would expose the key to anyone viewing the page. For browser use, either proxy through your backend or use the widget channel which authenticates with a public workspace token plus per-domain rate limiting.
HTTPS only. Plain HTTP is redirected to HTTPS; always call https://.

Common pitfalls

401 Unauthorized. Authorization header is malformed. Must be exactly Bearer ak_xxx. No "Token" or "Key" prefix.

403 Forbidden. Your plan does not include API access. The API needs Starter or above.

429 Too Many Requests. You hit a rate limit. Back off with increasing delays, then retry.

Empty or placeholder sources. Your workspace may have no indexed content yet. Check the Knowledge page.

Slow answers. Answer time depends mostly on the model your workspace uses and the length of the answer. Use the streaming endpoint so users see text as it is written.

FAQ

Is there an official SDK?

JavaScript and Python clients are on the roadmap. Until they ship, call the REST API directly; the requests are small JSON bodies.

Can I batch requests?

Not yet. Each query is one HTTP request. For high-throughput batch use cases, send concurrent requests with a connection pool. Rate limits apply per-key.

Can I cache responses?

Yes, at your application layer if you like. AskVault also keeps its own answer cache, which is cleared when your knowledge changes. If your queries are stable (same question expected to give same answer for hours), cache aggressively in your app.

How do I migrate from another chatbot API?

The /v1/query request shape is different from OpenAI's Chat Completions API: send {"query": "..."} (plus an optional session_id) instead of a messages array. Adapt the response parsing to use answer instead of choices[0].message.content.

Is there a sandbox for testing?

No separate sandbox mode. The API requires Starter or above, Free doesn't include API access, and every successful query on a live key counts against your monthly message quota.

Was this page helpful?