> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # See the documents a widget's AI answers from > The `ai-answers` adapter lets a widget answer a visitor's question with text an AI model writes from documents the widget's owner provides. This lists those documents, and how much room is left for more: `totals` carries the widget's limits next to what it uses. The list never contains what a document says, only which documents there are: their title, size and state. A `processing` document is not used to answer questions yet (or an add of it was interrupted: remove it and add it again). Add a document with `addAiAnswersKnowledgeDocument`; remove one with `removeAiAnswersKnowledgeDocument`. The caller must be allowed to see the widget: its owner, a partner for a customer it manages, or a Widgetic administrator. An API key needs the `content:read` scope. ## OpenAPI ````yaml /openapi/widgetic-api-public.json get /compositions/{id}/adapters/ai-answers/knowledge openapi: 3.0.0 info: title: Widgetic API Gateway version: 1.0.0 description: API documentation for the Widgetic API Gateway license: name: Widgetic Integration License url: https://docs.widgetic.com/resources/license servers: - url: https://api.widgetic.com/v1 description: Production server variables: env: default: production description: Environment apiUrl: default: https://api.widgetic.com description: API URL apiVersion: default: /v1 description: API Version path prefix security: [] tags: [] paths: /compositions/{id}/adapters/ai-answers/knowledge: get: tags: - Compositions summary: See the documents a widget's AI answers from description: > The `ai-answers` adapter lets a widget answer a visitor's question with text an AI model writes from documents the widget's owner provides. This lists those documents, and how much room is left for more: `totals` carries the widget's limits next to what it uses. The list never contains what a document says, only which documents there are: their title, size and state. A `processing` document is not used to answer questions yet (or an add of it was interrupted: remove it and add it again). Add a document with `addAiAnswersKnowledgeDocument`; remove one with `removeAiAnswersKnowledgeDocument`. The caller must be allowed to see the widget: its owner, a partner for a customer it manages, or a Widgetic administrator. An API key needs the `content:read` scope. operationId: getAiAnswersKnowledge parameters: - in: path name: id required: true schema: type: string format: uuid description: The widget (composition) whose documents to list - $ref: '#/components/parameters/ManagedUserScopeId' - $ref: '#/components/parameters/ManagedUserScopeExternalId' responses: '200': description: The documents of the widget and its totals content: application/json: schema: type: object properties: success: type: boolean data: $ref: '#/components/schemas/AiAnswersKnowledge' meta: $ref: '#/components/schemas/ResponseMeta' required: - success - data '400': description: The widget id is not a valid id content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The widget belongs to another account, or the API key lacks the `content:read` scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: There is no such widget content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests. Wait a minute. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- The knowledge base cannot be read on this server right now (KNOWLEDGE_UNAVAILABLE) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKeyAuth: [] x-code-samples: - lang: TypeScript label: TypeScript SDK source: > import { Configuration, CompositionsApi } from '@widgetic/api-sdk-ts'; const compositionsApi = new CompositionsApi(new Configuration({ apiKey: 'YOUR_API_KEY' })); const { data: { documents, totals } } = await compositionsApi.getAiAnswersKnowledge({ id: compositionId }); console.log(`${totals.documents} of ${totals.maxDocuments} documents`, documents.map((document) => document.title)); components: parameters: ManagedUserScopeId: in: header name: X-Managed-User-Id required: false description: >- 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. schema: type: string format: uuid example: 3f2b8c1e-7a4d-4e0b-9c55-2d1a6b7e8f90 ManagedUserScopeExternalId: in: header name: X-Managed-User-External-Id required: false description: >- 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. schema: type: string minLength: 1 maxLength: 255 example: customer-1042 schemas: AiAnswersKnowledge: type: object required: - documents - totals properties: documents: type: array description: Oldest first items: $ref: '#/components/schemas/AiAnswersKnowledgeDocument' totals: $ref: '#/components/schemas/AiAnswersKnowledgeTotals' example: documents: - Example AiAnswersKnowledgeDocument totals: null ResponseMeta: type: object description: >- 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. additionalProperties: true properties: page: type: integer description: The page that was read, counting from 1. example: 1 size: type: integer description: How many items one page holds. example: 20 total: type: integer description: How many items the whole list has. example: 135 limit: type: integer description: The same as `size`. example: 20 offset: type: integer description: How many items come before this page. example: 0 hasNextPage: type: boolean example: true hasPreviousPage: type: boolean example: false nextCursor: type: string nullable: true description: >- Pass this as `cursor` to read the next page of a list that is read by cursor. `null` on the last page. warnings: type: array items: type: string description: >- Things the call did not do, though it succeeded (for example a table that could not be created just now). ErrorResponse: type: object required: - success - message - error additionalProperties: true properties: success: type: boolean description: Always `false` on a failure. example: false message: type: string description: The same text as `error.message`, for a caller that reads one line. error: $ref: '#/components/schemas/ErrorDetail' AiAnswersKnowledgeDocument: type: object description: >- 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. required: - id - title - status - charCount - chunkCount - createdAt - readyAt properties: id: type: string format: uuid description: Use it to remove the document title: type: string maxLength: 120 description: >- What the document is called. Visitors see it as the source of an answer, so write it for them example: Shipping and returns status: type: string enum: - processing - ready description: >- `ready` documents are used to answer questions. A `processing` document is not: it is being added, or an add was interrupted. Remove one that stays in this state and add it again charCount: type: integer description: How many characters of text the document holds, after it was cleaned example: 4210 chunkCount: type: integer description: >- Into how many passages the text was cut. Zero until the document is ready example: 6 createdAt: type: string format: date-time readyAt: type: string format: date-time nullable: true description: When the document became ready. Null while it is not 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' AiAnswersKnowledgeTotals: type: object required: - documents - characters - maxDocuments - maxTotalChars properties: documents: type: integer description: How many documents the widget has characters: type: integer description: How many characters of text they hold in all maxDocuments: type: integer description: The most documents one widget can hold example: 20 maxTotalChars: type: integer description: The most characters of text one widget's documents can hold in all example: 400000 example: documents: 42 characters: 42 maxDocuments: 20 maxTotalChars: 400000 ErrorDetail: type: object required: - code - message - timestamp properties: code: type: string description: Machine-readable error code. example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation. example: Composition not found param: type: string description: The field that caused the error, when one did. example: name docUrl: type: string description: Where this error is explained. suggestedAction: type: string description: What to do about it. retryAfter: type: integer description: >- Seconds to wait before trying again (rate limits). The same number is in the `Retry-After` header. example: 60 details: type: object additionalProperties: true description: >- More about the error: the fields that failed, a limit that was reached. correlationId: type: string description: Quote this when you ask support about the call. example: req_123e4567-e89b-12d3-a456-426614174000 timestamp: type: string format: date-time example: '2026-10-15T10:00:00.000Z' securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.