API reference
Knowledge
Knowledge documents
| Method | Path | Summary |
|---|---|---|
GET | /v1/account/knowledge | Knowledge documents at account level and for groups |
POST | /v1/account/knowledge/ask | "Ask it a question": the passages the agent would find, and which document each came from |
POST | /v1/account/knowledge/text | Add pasted text; it is stored as a .txt file and embedded in the background |
POST | /v1/account/knowledge/upload | Upload a file (multipart: file, optional title and groupId fields). Text, Markdown, HTML or CSV. |
POST | /v1/account/knowledge/url | Add a web page by its address; it is fetched and embedded in the background |
DELETE | /v1/account/knowledge/{docId} | Delete a document, its chunks and its stored file |
Knowledge documents at account level and for groups#
GET /v1/account/knowledge
Authentication: Bearer token: Authorization: Bearer <token> (Supabase access token).
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
groupId | string (grp_… ID) | No | ID (grp_…) |
scope | enum | No | One of: "all", "account", "group". Default: "all". |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
docs | array<KnowledgeDoc> | Yes | — |
docs[].assetId | string | null | Yes | — |
docs[].createdAt | string (date-time) | Yes | — |
docs[].embeddedAt | string (date-time) | null | Yes | — |
docs[].error | string | null | Yes | — |
docs[].groupId | string (grp_… ID) | null | Yes | — |
docs[].id | string (kdoc_… ID) | Yes | ID (kdoc_…) |
docs[].sourceType | enum | Yes | One of: "upload", "url", "text". |
docs[].sourceUrl | string | null | Yes | — |
docs[].status | enum | Yes | One of: "pending", "processing", "ready", "failed". |
docs[].title | string | Yes | — |
docs[].updatedAt | string (date-time) | Yes | — |
Errors: 400, 401, 403, 404, 409, 429, 500, with an ErrorBody body.
Example
curl -X GET "$ANSWERSTACK_API_URL/v1/account/knowledge" \
-H "Authorization: Bearer $ACCESS_TOKEN""Ask it a question": the passages the agent would find, and which document each came from#
POST /v1/account/knowledge/ask
Authentication: Bearer token: Authorization: Bearer <token> (Supabase access token). Bearer token: Authorization: Bearer <token> (An API token (ans_pat_ or ans_svc_). Only routes that list a scope here accept one, and only with that scope.).
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | string (grp_… ID) | No | ID (grp_…) |
limit | integer | No | Between 1 and 10. Default: 3. |
playbookId | string (pb_… ID) | No | ID (pb_…) |
question | string | Yes | 2–500 characters. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
passages | array<object> | Yes | — |
passages[].content | string | Yes | — |
passages[].docId | string (kdoc_… ID) | Yes | ID (kdoc_…) |
passages[].isGroupDoc | boolean | Yes | — |
passages[].similarity | number | Yes | — |
passages[].title | string | Yes | — |
Errors: 400, 401, 403, 404, 409, 429, 500, with an ErrorBody body.
Example
curl -X POST "$ANSWERSTACK_API_URL/v1/account/knowledge/ask" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"question": "string"
}'Add pasted text; it is stored as a .txt file and embedded in the background#
POST /v1/account/knowledge/text
Authentication: Bearer token: Authorization: Bearer <token> (Supabase access token). Bearer token: Authorization: Bearer <token> (An API token (ans_pat_ or ans_svc_). Only routes that list a scope here accept one, and only with that scope.).
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | string (grp_… ID) | No | ID (grp_…) |
text | string | Yes | 1–200000 characters. |
title | string | Yes | 1–200 characters. |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
assetId | string | null | Yes | — |
createdAt | string (date-time) | Yes | — |
embeddedAt | string (date-time) | null | Yes | — |
error | string | null | Yes | — |
groupId | string (grp_… ID) | null | Yes | — |
id | string (kdoc_… ID) | Yes | ID (kdoc_…) |
sourceType | enum | Yes | One of: "upload", "url", "text". |
sourceUrl | string | null | Yes | — |
status | enum | Yes | One of: "pending", "processing", "ready", "failed". |
title | string | Yes | — |
updatedAt | string (date-time) | Yes | — |
Errors: 400, 401, 403, 404, 409, 429, 500, with an ErrorBody body.
Example
curl -X POST "$ANSWERSTACK_API_URL/v1/account/knowledge/text" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "string",
"text": "string"
}'Upload a file (multipart: file, optional title and groupId fields). Text, Markdown, HTML or CSV.#
POST /v1/account/knowledge/upload
Authentication: Bearer token: Authorization: Bearer <token> (Supabase access token).
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
assetId | string | null | Yes | — |
createdAt | string (date-time) | Yes | — |
embeddedAt | string (date-time) | null | Yes | — |
error | string | null | Yes | — |
groupId | string (grp_… ID) | null | Yes | — |
id | string (kdoc_… ID) | Yes | ID (kdoc_…) |
sourceType | enum | Yes | One of: "upload", "url", "text". |
sourceUrl | string | null | Yes | — |
status | enum | Yes | One of: "pending", "processing", "ready", "failed". |
title | string | Yes | — |
updatedAt | string (date-time) | Yes | — |
Errors: 400, 401, 403, 404, 409, 429, 500, with an ErrorBody body.
Example
curl -X POST "$ANSWERSTACK_API_URL/v1/account/knowledge/upload" \
-H "Authorization: Bearer $ACCESS_TOKEN"Add a web page by its address; it is fetched and embedded in the background#
POST /v1/account/knowledge/url
Authentication: Bearer token: Authorization: Bearer <token> (Supabase access token).
Request body
application/json, required.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | string (grp_… ID) | No | ID (grp_…) |
title | string | No | 1–200 characters. |
url | string | Yes | 1–2000 characters. |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
assetId | string | null | Yes | — |
createdAt | string (date-time) | Yes | — |
embeddedAt | string (date-time) | null | Yes | — |
error | string | null | Yes | — |
groupId | string (grp_… ID) | null | Yes | — |
id | string (kdoc_… ID) | Yes | ID (kdoc_…) |
sourceType | enum | Yes | One of: "upload", "url", "text". |
sourceUrl | string | null | Yes | — |
status | enum | Yes | One of: "pending", "processing", "ready", "failed". |
title | string | Yes | — |
updatedAt | string (date-time) | Yes | — |
Errors: 400, 401, 403, 404, 409, 429, 500, with an ErrorBody body.
Example
curl -X POST "$ANSWERSTACK_API_URL/v1/account/knowledge/url" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "string"
}'Delete a document, its chunks and its stored file#
DELETE /v1/account/knowledge/{docId}
Authentication: Bearer token: Authorization: Bearer <token> (Supabase access token).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
docId | string (kdoc_… ID) | Yes | ID (kdoc_…) |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
deleted | enum | Yes | One of: true. |
Errors: 400, 401, 403, 404, 409, 429, 500, with an ErrorBody body.
Example
curl -X DELETE "$ANSWERSTACK_API_URL/v1/account/knowledge/{docId}" \
-H "Authorization: Bearer $ACCESS_TOKEN"