API

REST API reference

Base URL https://api.asklify.in/api/v1 · authenticated with Authorization: Bearer sk_... — see Authentication. Org-wide keys must pass projectId on every call; project-scoped keys must not.

Send a chat message

POST/chat

Sends an end-user message and returns the assistant's grounded answer. Requires the chat scope. Omit conversationId to start a new conversation; pass the one you received back to continue it.

Field	Type	Description
`message`required	string	The user's message (max 4,000 chars).
`conversationId`	string	Continue an existing conversation.
`endUserId`	string	Your stable identifier for the end user — threads their conversations across sessions.
`stream`	boolean	When true, the response is streamed as server-sent events.
`projectId`	string	Required for org-wide keys only.

cURL

curl https://api.asklify.in/api/v1/chat \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Do you offer refunds on annual plans?",
    "endUserId": "user_42"
  }'

Response:

json

{
  "conversationId": "cm_abc123",
  "messageId": "cm_msg456",
  "content": "Yes — annual plans are eligible for a full refund within 30 days...",
  "citations": [
    {
      "documentId": "cm_doc789",
      "documentName": "Billing Policy.pdf",
      "chunkId": "cm_chk012",
      "score": 0.89
    }
  ],
  "confidence": 0.86,
  "latencyMs": 1240
}

Streaming

With "stream": true the endpoint responds with text/event-stream. Each event's data is a JSON object with a type:

Field	Type	Description
`meta`	event	First event: `conversationId` and `messageId`.
`delta`	event	A chunk of answer text in `text`. Concatenate deltas to build the reply.
`sources`	event	Citations and confidence, once retrieval completes.
`done`	event	Final event with the complete response payload.
`error`	event	Something failed mid-stream; `message` explains.

stream.ts

const res = await fetch("https://api.asklify.in/api/v1/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ASKLIFY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "How do I reset my password?", stream: true }),
});

const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  for (const frame of buffer.split("\n\n")) {
    if (!frame.startsWith("data:")) continue;
    const event = JSON.parse(frame.slice(5));
    if (event.type === "delta") process.stdout.write(event.text);
  }
  buffer = buffer.slice(buffer.lastIndexOf("\n\n") + 2);
}

Knowledge

GET/knowledge/documents

Lists documents in the project. Scope: knowledge:read. Supports page, limit, and search query params.

POST/knowledge/documents

Creates a document from raw text. Scope: knowledge:write. Ingestion (chunking + embedding) runs asynchronously — the document's status moves from PROCESSING to READY.

bash

curl https://api.asklify.in/api/v1/knowledge/documents \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund policy",
    "content": "Full refunds are available within 30 days of purchase..."
  }'

POST/knowledge/documents/upload

Uploads a file as multipart/form-data (field name file). PDF, DOCX, TXT, CSV, and Markdown are supported. For org-wide keys pass ?projectId=....

bash

curl https://api.asklify.in/api/v1/knowledge/documents/upload \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "file=@./product-guide.pdf"

DELETE/knowledge/documents/{documentId}

Deletes a document and its indexed chunks. Scope: knowledge:write.

POST/knowledge/search

Semantic search over your indexed knowledge — the same retrieval the assistant uses. Scope: knowledge:read.

Field	Type	Description
`query`required	string	Natural-language search query.
`limit`	number	Max results (default 5).
`projectId`	string	Required for org-wide keys only.

Conversations

GET/conversations

Lists conversations with pagination and filters. Scope: conversations:read.

GET/conversations/{conversationId}

Returns one conversation including its full message transcript.

Human handoff

POST/handoff

Escalates a conversation to your team — it appears in the dashboard inbox and triggers the human.requested webhook. Scope: chat.

Field	Type	Description
`conversationId`required	string	The conversation to escalate.
`email`	string	End user's contact email.
`name`	string	End user's name.
`reason`	string	Why the handoff was requested.
`projectId`	string	Required for org-wide keys only.

Usage

GET/usage

Current billing-period usage for your organization (messages, storage, tokens). Scope: analytics:read.

Rate limits apply per key. When exceeded you'll receive 429 Too Many Requests — honor the Retry-After header and back off exponentially.