Add a Knowledge document

Add a document Agents can consult. kind: text takes text (plain text or Markdown); kind: file takes file (base64, up to 8 MiB: PDF, Word, Excel, HTML, CSV, plain text or Markdown); kind: website takes an approved HTTPS sourceUrl and optional crawl bounds and starts a crawl task (list_tasks with kind=knowledge_crawl). Indexing follows on its own: the document is searchable once indexStatus is ready (check with get_knowledge_document). Then give it to Agents with update_agent (knowledgeDocumentIds).

Scope: raiz:knowledge:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; not idempotent: check the outcome before you retry
Limits: request body up to 12 MB, response up to 1 MB
CLI: arbol raiz knowledge create · MCP tool: raiz_knowledge_create

POST

https://api.getarbol.com/v1/raiz/knowledge

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope raiz:knowledge:write. Get an API key.

Request body JSON required

kind
text
or
file
or
website
required
text: written inline. file: an uploaded document (PDF, Word, Excel, HTML, CSV, plain text or Markdown). website: a snapshot of approved web pages.
title
string
required
maxLength: 200 · minLength: 1
crawl
optional
object
Website documents only. Default: 20 pages, depth 2.
- maxDepth
  integer
  required
  Path depth below the source URL to follow; 0 imports only that page.
  
  maximum: 5 · minimum: 0
- maxPages
  integer
  required
  Pages to import at most.
  
  maximum: 50 · minimum: 1
}
description
optional
string | null
maxLength: 2000
file
optional
object
File documents only.
- data
  string
  required
  The file's bytes in standard base64, at most 8 MiB decoded.
  
  maxLength: 11184812 · minLength: 4
- mediaType
  application/pdf
  or
  application/vnd.openxmlformats-officedocument.wordprocessingml.document
  or
  application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  or
  text/csv
  or
  text/html
  or
  text/markdown
  +1 more
  required
  The file's media type; it must match its content.
- name
  string
  required
  File name, for people (Tarifas 2026.pdf).
  
  maxLength: 200 · minLength: 1 · pattern: ^[^/\\\u0000-\u001f\u007f]+$
}
sourceUrl
optional
string
Website documents only: the HTTPS page to start from. Its origin must be approved for this deployment; only same-origin pages under its path are followed, and robots.txt is respected.

format: uri · maxLength: 2048 · pattern: ^https://
status
optional
active
or
paused
A paused document is never searched; its index is kept.
text
optional
string
Text documents only: the content, plain text or Markdown.

maxLength: 1000000 · minLength: 1

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- byteSize
  integer | null
  required
  Size of the stored source, bytes.
  
  minimum: 0
- createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- description
  string | null
  required
- fileName
  string | null
  required
- id
  string
  required
  Knowledge document id.
  
  pattern: ^(?:kdc_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:con)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- indexErrorCode
  string | null
  required
  Why the last indexing failed.
- indexedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- indexStatus
  pending
  or
  indexing
  or
  ready
  or
  failed
  required
  pending: waiting to be crawled or indexed. indexing: in progress. ready: searchable. failed: see indexErrorCode; failed documents are retried automatically.
- kind
  text
  or
  file
  or
  website
  required
  text: written inline. file: an uploaded document (PDF, Word, Excel, HTML, CSV, plain text or Markdown). website: a snapshot of approved web pages.
- mediaType
  string | null
  required
- sha256
  string | null
  required
  SHA-256 of the stored source, hex.
- sourceUrl
  string | null
  required
- status
  active
  or
  paused
  required
  A paused document is never searched; its index is kept.
- title
  string
  required
- updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- version
  integer
  required
  minimum: 1
- content
  optional
  object
  The extracted text. Null until the document was indexed once. Present only when expanded.
  
  text
  string
  required
  The text as indexed (Markdown), at most 200000 characters.
  
  truncated
  boolean
  required
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

422

KNOWLEDGE_FILE_INVALID: The file is not valid base64, exceeds the size limit or does not match its declared type.
KNOWLEDGE_KIND_MISMATCH: The change does not apply to this kind of Knowledge document.
WEBSITE_NOT_APPROVED: This website's origin is not approved for crawling in this deployment.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}