Add a document for a widget's AI to answer from

Gives the widget’s AI a document to answer visitors’ questions from. Send the title and the plain text. The call returns once the document is ready to be used, which takes a few seconds, longer for a long text.

How it is used. The text is cleaned, cut into short passages and each passage is turned into numbers (an embedding) so the widget can find the passages nearest to a question. When a visitor asks, the nearest passages and the question are shown to an AI model, which writes the answer from them and from nothing else; if the documents say nothing about the question the visitor is told so, and the owner is not charged for that question. The titles of the documents an answer used are shown to the visitor as its sources.

What leaves Widgetic. The text of a document is sent to OpenAI to be embedded when it is added, and the passages used for a question are sent to the AI model that writes the answer. Say so in your privacy policy.

Treat every document as public. An answer can quote or paraphrase anything a document says, to any visitor of the widget. Do not add passwords, keys, personal data or anything that must stay private.

Limits. A widget holds up to 20 documents, each up to 100000 characters, and up to 400000 characters in all (getAiAnswersKnowledge reports the current numbers). This call takes text. To add a text file or a picture of a document (a PDF too, once PDFs are read) without turning it into text yourself, use addAiAnswersKnowledgeFile. Adding a document costs no credits. The same text cannot be added twice to one widget (409).

The caller must be allowed to change the widget. An API key needs the content:write scope. Adds are limited to ten in ten minutes per person. A partner’s customer in an editor session is one person of its own: its adds are not counted with the partner’s other customers’.

POST /compositions/{id}/adapters/ai-answers/knowledge/documents

TypeScript SDK

TypeScript

import { Configuration, CompositionsApi } from '@widgetic/api-sdk-ts';

const compositionsApi = new CompositionsApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));

const { data: document } = await compositionsApi.addAiAnswersKnowledgeDocument({
  id: compositionId,
  addAiAnswersKnowledgeDocumentRequest: {
    title: 'Shipping and returns',
    text: 'Orders ship within 2 business days. Returns are accepted for 30 days after delivery.',
  },
});
console.log(document.id, document.status);

201

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Shipping and returns",
    "status": "Example status",
    "charCount": 4210,
    "chunkCount": 6,
    "createdAt": "2026-01-15T09:30:00.000Z",
    "readyAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Managed-User-Id · string<uuid>

The id Widgetic gave the managed user (POST /managed-users). Makes this call for one of your managed users, so that a mistake in your own code cannot reach another customer's work. Send this header, or the other one, never both. Left out, the call works on your whole account, as it always has. With it, the call reaches only that user's compositions and workflows: a list shows only theirs, a composition or a workflow the call makes is filed under them, and one of another user, or one that does not exist, answers 404 (the same answer, so the call cannot be used to find out what another customer has). A managed user that is not yours answers 404 with MANAGED_USER_NOT_FOUND. An empty, repeated or malformed header is 400 with MANAGED_USER_SCOPE_INVALID; an empty header is never read as no header. A call that is about the whole account, such as the list of your managed users, is refused with 403 and MANAGED_USER_SCOPE_ROUTE_NOT_AVAILABLE: send it without the header. Only your API key can send it. The header is a limit the call asks for: whoever holds the key can leave it out, so for a credential that a customer's browser holds, use an editor session. An Idempotency-Key is kept apart for each managed user.

Example:

"3f2b8c1e-7a4d-4e0b-9c55-2d1a6b7e8f90"

X-Managed-User-External-Id · string

Your own id for the managed user (its externalId), when you do not keep Widgetic's. Makes this call for one of your managed users, so that a mistake in your own code cannot reach another customer's work. Send this header, or the other one, never both. Left out, the call works on your whole account, as it always has. With it, the call reaches only that user's compositions and workflows: a list shows only theirs, a composition or a workflow the call makes is filed under them, and one of another user, or one that does not exist, answers 404 (the same answer, so the call cannot be used to find out what another customer has). A managed user that is not yours answers 404 with MANAGED_USER_NOT_FOUND. An empty, repeated or malformed header is 400 with MANAGED_USER_SCOPE_INVALID; an empty header is never read as no header. A call that is about the whole account, such as the list of your managed users, is refused with 403 and MANAGED_USER_SCOPE_ROUTE_NOT_AVAILABLE: send it without the header. Only your API key can send it. The header is a limit the call asks for: whoever holds the key can leave it out, so for a credential that a customer's browser holds, use an editor session. An Idempotency-Key is kept apart for each managed user.

Required string length: 1 - 255

Example:

"customer-1042"

Path Parameters

id · string<uuid> · required

The widget (composition) to add the document to

Body

application/json

title · string · required

What the document is called, on one line. Visitors see it as the source of an answer. Line breaks and invisible characters are removed

Maximum string length: 120

Example:

"Shipping and returns"

text · string · required

The text of the document, as plain text. It is cleaned (line endings are made the same, invisible characters and surplus blank lines are removed) and then counted: up to 100000 characters. Markup is not interpreted, so paste the words, not a web page

Maximum string length: 100000

Example:

"Orders ship within 2 business days. Returns are accepted for 30 days after delivery, in the original packaging."

Response

201

application/json

The document was added and is ready to be used

success · boolean · required

data · object · required

One document in a widget's knowledge base: what the widget's AI answers visitors' questions from. Its text is not part of this: it is kept so the widget can find the passages that answer a question, and is never returned.

Show child attributes

Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Shipping and returns",
  "status": "Example status",
  "charCount": 4210,
  "chunkCount": 6,
  "createdAt": "2026-01-15T09:30:00.000Z",
  "readyAt": "2026-01-15T09:30:00.000Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes