Knowledge

Collections knowledge

Collections knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

{
  "object": "list",
  "data": [
    {
      "object": "knowledge_collection",
      "id": 1,
      "name": "Help centre",
      "description": "Eius molestias omnis est debitis est vero.",
      "chatbot_id": 1,
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/knowledge/collections"
}

curl -X GET https://api.agentency.com/v1/knowledge/collections \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Show collection knowledge

Show collection knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

curl -X GET https://api.agentency.com/v1/knowledge/collections/{id} \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Usage knowledge

Usage knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

{
  "object": "knowledge_usage",
  "id": 1,
  "per_agent_limit": 409600,
  "pool_limit": 0,
  "pool_used": 0,
  "extra_packs": 0
}

curl -X GET https://api.agentency.com/v1/knowledge/usage \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Stats knowledge

Stats knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

curl -X GET https://api.agentency.com/v1/knowledge/stats \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

List knowledges

List knowledges. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Rows whose background removal is in flight are included with `is_deleting: true`; inactive rows are not.

Required scopeknowledge:read

{
  "object": "list",
  "data": [
    {
      "object": "knowledge_dataset",
      "id": 1,
      "name": "Refund policy",
      "description": "Repellendus cum expedita reiciendis quis culpa neque cupiditate. Consequatur iure voluptatem possimus doloribus voluptas omnis minima. Tempora molestiae enim ratione. Similique maxime asperiores quis occaecati rerum beatae.",
      "type": "PDF",
      "source_type": "url",
      "source_url": null,
      "status": "uploaded",
      "embedding_status": "not_started",
      "embedding_processed_at": null,
      "total_chunks": 0,
      "total_words": 100,
      "collection_id": 1,
      "chatbot_id": 1,
      "is_deleting": false,
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/knowledge"
}

curl -X GET https://api.agentency.com/v1/knowledge \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Create a knowledge

Create a knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "name": "name",
  "description": "description",
  "type": "type",
  "source_type": "source_type",
  "content": "content",
  "source_url": "source_url",
  "category": "category",
  "tags": "tags"
}'

Retrieve a knowledge

Retrieve a knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

{
  "object": "knowledge_dataset",
  "id": 1,
  "name": "Refund policy",
  "description": "Repellendus cum expedita reiciendis quis culpa neque cupiditate. Consequatur iure voluptatem possimus doloribus voluptas omnis minima. Tempora molestiae enim ratione. Similique maxime asperiores quis occaecati rerum beatae.",
  "type": "PDF",
  "source_type": "url",
  "source_url": null,
  "status": "uploaded",
  "embedding_status": "not_started",
  "embedding_processed_at": null,
  "total_chunks": 0,
  "total_words": 100,
  "collection_id": 1,
  "chatbot_id": 1,
  "is_deleting": false,
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

curl -X GET https://api.agentency.com/v1/knowledge/{id} \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Update a knowledge

Update a knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Renaming to a name another active dataset already uses is 409 `KNOWLEDGE_NAME_TAKEN`. `content` replaces the inline text of a `text`-sourced dataset (any other source is 422 `VALIDATION_FAILED`); when the dataset is already trained, `retrain` (default true) re-embeds every chatbot that uses it, or saves the text and keeps the current vectors when false. A dataset being removed is 409 `DATASET_DELETING`.

Required scopeknowledge:write

curl -X PATCH https://api.agentency.com/v1/knowledge/{id} \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "name": "name",
  "description": "description",
  "category": "category",
  "tags": "tags",
  "is_public": true,
  "content": "content",
  "retrain": true
}'

Delete a knowledge

Delete a knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:write

curl -X DELETE https://api.agentency.com/v1/knowledge/{id} \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Chunks knowledge

Chunks knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

curl -X GET https://api.agentency.com/v1/knowledge/{id}/chunks \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Status knowledge

Status knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

{
  "object": "knowledge_status",
  "id": 1,
  "status": "uploaded",
  "embedding_status": "not_started",
  "total_chunks": 0,
  "is_deleting": false
}

curl -X GET https://api.agentency.com/v1/knowledge/{id}/status \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Chatbot knowledge knowledge

Chatbot knowledge knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

curl -X GET https://api.agentency.com/v1/chatbots/{id}/knowledge \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Chatbot knowledge status knowledge

Chatbot knowledge status knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. `counts` buckets the chatbot's active datasets by training state — `total`, `processing` (queued for or currently embedding), `failed`, `completed`, `queued` (added but not yet trained) — plus `removing`, the datasets whose deletion is still running in the background.

Required scopeknowledge:read

curl -X GET https://api.agentency.com/v1/chatbots/{id}/knowledge/status \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Removal impact knowledge

Removal impact knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:read

curl -X POST https://api.agentency.com/v1/knowledge/removal_impact \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "knowledge_ids": [],
  "chatbot_id": 1,
  "confirm_deletion": "confirm_deletion"
}'

Retry knowledge

Retry knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Queues a full re-embed of the dataset for its chatbot, clearing the previous attempt's error and any pending cancellation. A dataset that is currently being processed is 409 `INGESTION_IN_PROGRESS` (cancel it first); one with no chatbot is 422 `CHATBOT_REQUIRED`; one being removed is 409 `DATASET_DELETING`.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/{id}/retry \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Recrawl knowledge

Recrawl knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Queues a re-fetch of a dataset whose content came from a URL (`source_type` `url`, `url_links` or `sitemap`); anything else is 409 `DATASET_NOT_URL_SOURCED`. While a fetch is running the dataset reports `crawler_status: running` and a second call is 409 `RECRAWL_IN_PROGRESS`. A dataset being removed is 409 `DATASET_DELETING`.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/{id}/recrawl \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Cancel knowledge

Cancel knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/{id}/cancel \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Replace file knowledge

Replace file knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Swaps the document behind an uploaded dataset: the new file's text is extracted (or sent to OCR for images / scanned PDFs), replaces the dataset content, and every chatbot trained on the old content is re-embedded. Only `source_type: upload` datasets qualify (422 `DATASET_NOT_UPLOAD_SOURCED`); a file with no readable text is 422 `TEXT_EXTRACTION_FAILED` and leaves the dataset untouched. A dataset being removed is 409 `DATASET_DELETING`.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/{id}/replace_file \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "file": "file"
}'

Import cloud knowledge

Import cloud knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/import/cloud \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "provider": "provider",
  "chatbot_id": 1,
  "knowledge_collection_id": 1,
  "auto_train": "auto_train",
  "idempotency_key": "idempotency_key",
  "access_token": "access_token",
  "files": []
}'

Retry bulk knowledge

Retry bulk knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Per-row semantics identical to `POST /v1/knowledge/{id}/retry`, but a row that cannot be retried is skipped and counted in `skipped` / `skipped_by_reason` (`processing`, `deleting`, `no_chatbot`) instead of failing the batch. Unknown ids are absent from both counts.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/retry \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "knowledge_ids": []
}'

Retry failed knowledge

Retry failed knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Same coordinator as the dashboard's chatbot-scoped retry ({@see KnowledgeTrainingController::retryFailedForChatbot()}): the request plucks a capped id set and dispatches ONE {@see RetryFailedEmbeddingsBatch}; the per-dataset state reset and re-embed fan-out run on the queue. Looping the datasets here (one UPDATE + one dispatch each, unbounded by anything but the bot's library size) made a large failed crawl a multi-second request and a queue storm.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/{id}/retry_failed \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Train collected knowledge

Train collected knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed. Covers the bot's `not_started` datasets (collected with auto-train off) AND its `failed` ones, as this endpoint always has. Both buckets are handed to the coordinators the dashboard uses — a chatbot can own tens of thousands of collected pages, so ids are never looped at HTTP time: {@see TrainCollectedKnowledgeBatch} cursors the `not_started` rows on the queue and {@see RetryFailedEmbeddingsBatch} takes the capped failed id set. `queued` is the number of datasets those coordinators will claim.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/{id}/train_collected \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Remove from chatbot knowledge

Remove from chatbot knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/remove_from_chatbot \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "knowledge_ids": [],
  "chatbot_id": 1,
  "confirm_deletion": "confirm_deletion"
}'

Remove from system knowledge

Remove from system knowledge. Authenticate with a bearer API key that includes the required scope. Resources that belong to another account return 404 NOT_FOUND. Mutations accept Idempotency-Key and emit a webhook event when they succeed.

Required scopeknowledge:write

curl -X POST https://api.agentency.com/v1/knowledge/remove_from_system \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "knowledge_ids": [],
  "chatbot_id": 1,
  "confirm_deletion": "confirm_deletion"
}'