Knowledge base

Get started

Guides

REST reference

Knowledge Base API

Knowledge sources the AI agent learns from (text, Q&A, websites, files) and knowledge base articles.

View as Markdown

List knowledge base articles

GET/v1/knowledge_base/articles

Cursor-paginated articles, newest first.

Required scope: knowledge_base:read.

Parameters

limitinteger

Page size (1–100).

starting_afterstring

Cursor: the `id` of the last item from the previous page.

statusstring

One of: draft, published.

typestring

One of: public_article, internal_article.

Request

cURL

curl "https://api.asks.app/v1/knowledge_base/articles" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "knowledge_base_article",
      "id": "string",
      "title": "string",
      "content": "string",
      "description": {},
      "tags": [
        "string"
      ],
      "category": {},
      "status": "draft",
      "type": "public_article",
      "is_public": true,
      "ai_agent_enabled": true,
      "indexed": true,
      "created_at": {},
      "updated_at": {}
    }
  ],
  "has_more": true,
  "next_cursor": {}
}

Retrieve a knowledge base article

GET/v1/knowledge_base/articles/{id}

Required scope: knowledge_base:read.

Request

cURL

curl "https://api.asks.app/v1/knowledge_base/articles/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "knowledge_base_article",
  "id": "string",
  "title": "string",
  "content": "string",
  "description": {},
  "tags": [
    "string"
  ],
  "category": {},
  "status": "draft",
  "type": "public_article",
  "is_public": true,
  "ai_agent_enabled": true,
  "indexed": true,
  "created_at": {},
  "updated_at": {}
}

Summarize knowledge sources

GET/v1/knowledge_base/summary

Counts of knowledge sources by type and status, total size and the last time anything finished training.

Required scope: knowledge_base:read.

Request

cURL

curl "https://api.asks.app/v1/knowledge_base/summary" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "knowledge_summary",
  "total": 1,
  "by_type": {},
  "by_status": {},
  "size_bytes": 1,
  "last_trained_at": {}
}

List knowledge sources

GET/v1/knowledge_base/sources

Everything the AI agent learns from, newest first: text and Q&A sources, websites (with their crawled page count) and uploaded files. Pages crawled from a website are counted on the website, not listed. next_cursor is opaque. With status, a page can hold fewer than limit items (even none) while has_more is true — keep paging.

Required scope: knowledge_base:read.

Parameters

limitinteger

Page size (1–100).

starting_afterstring

Cursor: the `id` of the last item from the previous page.

typestring

One of: text, qna, website, document.

statusstring

One of: draft, disabled, training, trained, failed, syncing.

qstring

Case-insensitive match on the source name.

Request

cURL

curl "https://api.asks.app/v1/knowledge_base/sources" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "list",
  "data": [
    {
      "object": "knowledge_source",
      "id": "string",
      "type": "text",
      "name": "string",
      "status": "draft",
      "url": {},
      "ai_enabled": true,
      "origin": {},
      "file_name": {},
      "size_bytes": 1,
      "page_count": {},
      "error": {},
      "last_trained_at": {},
      "last_synced_at": {},
      "created_at": {},
      "updated_at": {}
    }
  ],
  "has_more": true,
  "next_cursor": {}
}

Create a knowledge source

POST/v1/knowledge_base/sources

Adds knowledge and starts training it — there is no separate train step. text and qna sources are indexed as they are written and usually come back trained; a website is crawled in the background and comes back syncing — poll the source until it is trained or failed. Counts toward the plan's knowledge base limit. Files can only be uploaded in the dashboard.

Required scope: knowledge_base:write.

Request

cURL

curl -X POST "https://api.asks.app/v1/knowledge_base/sources" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 201

JSON

{
  "object": "knowledge_source",
  "id": "string",
  "type": "text",
  "name": "string",
  "status": "draft",
  "url": {},
  "ai_enabled": true,
  "origin": {},
  "file_name": {},
  "size_bytes": 1,
  "page_count": {},
  "error": {},
  "last_trained_at": {},
  "last_synced_at": {},
  "created_at": {},
  "updated_at": {},
  "content": "string",
  "questions": {},
  "answer": {},
  "config": {
    "url": {},
    "include_urls": [
      "string"
    ],
    "exclude_paths": [
      "string"
    ],
    "max_pages": {},
    "refresh": "never"
  },
  "recent_syncs": [
    {
      "status": "syncing",
      "pages": 1,
      "error": {},
      "started_at": {},
      "completed_at": {}
    }
  ]
}

Retrieve a knowledge source

GET/v1/knowledge_base/sources/{id}

Includes the full text (text, Q&A), the questions and answer (Q&A), or the crawl settings and the last 5 syncs (website).

Required scope: knowledge_base:read.

Request

cURL

curl "https://api.asks.app/v1/knowledge_base/sources/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "knowledge_source",
  "id": "string",
  "type": "text",
  "name": "string",
  "status": "draft",
  "url": {},
  "ai_enabled": true,
  "origin": {},
  "file_name": {},
  "size_bytes": 1,
  "page_count": {},
  "error": {},
  "last_trained_at": {},
  "last_synced_at": {},
  "created_at": {},
  "updated_at": {},
  "content": "string",
  "questions": {},
  "answer": {},
  "config": {
    "url": {},
    "include_urls": [
      "string"
    ],
    "exclude_paths": [
      "string"
    ],
    "max_pages": {},
    "refresh": "never"
  },
  "recent_syncs": [
    {
      "status": "syncing",
      "pages": 1,
      "error": {},
      "started_at": {},
      "completed_at": {}
    }
  ]
}

Update a knowledge source

PATCH/v1/knowledge_base/sources/{id}

Text and Q&A: new content overwrites the source and retrains it immediately — the previous text is gone. Websites: change the page selection, exclusions, page cap or auto-refresh (the URL is immutable — delete and recreate). Files can only be changed in the dashboard.

Required scope: knowledge_base:write.

Request body

namestring

contentstring

Text sources: replaces the content.

questionsarray of string

Q&A sources.

answerstring

Q&A sources.

ai_enabledboolean

Text and Q&A: switch the source on/off for the AI agent.

include_urlsarray of string

exclude_pathsarray of string

max_pagesinteger

refreshstring

One of: never, daily, weekly, monthly.

Request

cURL

curl -X PATCH "https://api.asks.app/v1/knowledge_base/sources/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "content": "string",
    "questions": [
      "string"
    ],
    "answer": "string",
    "ai_enabled": true,
    "include_urls": [
      "string"
    ],
    "exclude_paths": [
      "string"
    ],
    "max_pages": 1,
    "refresh": "never"
  }'

Response 200

JSON

{
  "object": "knowledge_source",
  "id": "string",
  "type": "text",
  "name": "string",
  "status": "draft",
  "url": {},
  "ai_enabled": true,
  "origin": {},
  "file_name": {},
  "size_bytes": 1,
  "page_count": {},
  "error": {},
  "last_trained_at": {},
  "last_synced_at": {},
  "created_at": {},
  "updated_at": {},
  "content": "string",
  "questions": {},
  "answer": {},
  "config": {
    "url": {},
    "include_urls": [
      "string"
    ],
    "exclude_paths": [
      "string"
    ],
    "max_pages": {},
    "refresh": "never"
  },
  "recent_syncs": [
    {
      "status": "syncing",
      "pages": 1,
      "error": {},
      "started_at": {},
      "completed_at": {}
    }
  ]
}

Delete a knowledge source

DELETE/v1/knowledge_base/sources/{id}

Removes the source and everything learned from it (a website takes its crawled pages with it). Immediate and permanent.

Required scope: knowledge_base:delete.

Request

cURL

curl -X DELETE "https://api.asks.app/v1/knowledge_base/sources/<id>" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 200

JSON

{
  "object": "knowledge_source",
  "id": "string",
  "type": "text",
  "deleted": true
}

Re-sync a website

POST/v1/knowledge_base/sources/{id}/sync

Re-crawls a website source in the background and answers 202 with the source syncing. Re-syncs follow the plan's refresh frequency (PLAN_LIMIT_REACHED when synced too recently).

Required scope: knowledge_base:write.

Request

cURL

curl -X POST "https://api.asks.app/v1/knowledge_base/sources/<id>/sync" \
  -H "Authorization: Bearer $ASKS_API_KEY"

Response 202

JSON

{
  "object": "knowledge_source",
  "id": "string",
  "type": "text",
  "name": "string",
  "status": "draft",
  "url": {},
  "ai_enabled": true,
  "origin": {},
  "file_name": {},
  "size_bytes": 1,
  "page_count": {},
  "error": {},
  "last_trained_at": {},
  "last_synced_at": {},
  "created_at": {},
  "updated_at": {},
  "content": "string",
  "questions": {},
  "answer": {},
  "config": {
    "url": {},
    "include_urls": [
      "string"
    ],
    "exclude_paths": [
      "string"
    ],
    "max_pages": {},
    "refresh": "never"
  },
  "recent_syncs": [
    {
      "status": "syncing",
      "pages": 1,
      "error": {},
      "started_at": {},
      "completed_at": {}
    }
  ]
}

← Previous

Tickets