API reference · Knowledge

Add a document

POSThttps://goblins-call-api.onrender.com/v1/knowledge/documents

Adds a document to your workspace. It is read in the background: the response comes back at once with the document processing.

Needs a workspace API key.

Query parameters

namestringOptional

The file’s name with its ending, such as Price list.pdf. Required when the body is a file.

userIdstringOptional

A workspace ID. A key belongs to one workspace, so this is never needed with one; naming another workspace answers 403.

Body

namestringRequiredup to 255 chars

What the document is called.

textstringRequired20–200,000 chars

The text itself.

Response

document.statusenum

processing while it is being read, then ready, or failed with the reason in error.

document.cardCountinteger

How many questions and answers were taken from it.

document.storedboolean

Whether the uploaded file itself is kept and can be downloaded again.

Errors

400

The body failed validation. details lists each field and what is wrong with it.

400NAME_REQUIRED

A file was sent without ?name=.

402INSUFFICIENT_BALANCE

The workspace balance is zero or below.

409DOCUMENT_LIMIT_REACHED

The workspace already holds 500 documents.

413FILE_TOO_LARGE

The file is larger than 25 MB.

415UNSUPPORTED_FILE_TYPE

The file is not a PDF, a Word .docx or a text file.

429RATE_LIMITED

The workspace has added too many documents in an hour. Its members and keys share the one allowance.

503KNOWLEDGE_BUSY

Many documents are waiting to be read. Send it again in a few minutes.

Every request can also answer 401, 429 and 500: see Errors.

Notes

  • To upload a file, send its bytes as the request body with Content-Type: application/octet-stream and its name in ?name=, instead of JSON. The Knowledge guide has the cURL for it.
  • Adding a document does not give it to any agent: put its ID in an agent’s documentIds.
curl -X POST "https://goblins-call-api.onrender.com/v1/knowledge/documents" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Refund policy",
  "text": "A refund for a cancelled order is paid within seven working days to the card that was used."
}'
Response · 202 Accepted
{
  "document": {
    "id": "kd_4b1f0c9d2e7a6f53",
    "userId": "usr_8c1d2e3f4a5b",
    "name": "Refund policy",
    "kind": "text",
    "bytes": 92,
    "status": "processing",
    "topics": [],
    "chars": 0,
    "cardCount": 0,
    "sectionCount": 0,
    "stored": false,
    "createdAt": "2026-10-12T09:30:00.000Z",
    "updatedAt": "2026-10-12T09:30:00.000Z"
  }
}