> ## Documentation Index > Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add a knowledge document > Add a text document to an agent's knowledge. The document is available from the next call. Empty text is saved without indexing. If indexing fails, the saved text remains available directly on calls. ## OpenAPI ````yaml /api-reference/v1/openapi.json post /v1/agents/{id}/knowledge-sources openapi: 3.1.0 info: description: >- Authenticate every request with an org API key: `Authorization: Bearer phk_…`. title: Phonely API version: '1' servers: - description: US url: https://api.us.phonely.ai - description: AU url: https://api.au.phonely.ai security: [] paths: /v1/agents/{id}/knowledge-sources: post: tags: - Agents summary: Add a knowledge document description: >- Add a text document to an agent's knowledge. The document is available from the next call. Empty text is saved without indexing. If indexing fails, the saved text remains available directly on calls. operationId: create_agent_knowledge_source parameters: - description: The agent's ID. in: path name: id required: true schema: description: The agent's ID. title: Id type: string - description: Optional. Must be the key's org. in: header name: Phonely-Organization required: false schema: anyOf: - type: string - type: 'null' description: Optional. Must be the key's org. title: Phonely-Organization requestBody: content: application/json: schema: $ref: '#/components/schemas/KnowledgeSourceCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/KnowledgeSource' description: Successful Response headers: Phonely-Organization: description: The authorized organization for this request. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request is invalid: a malformed body, a bad or unknown field, or an unknown query parameter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The API key is missing, invalid or revoked. headers: WWW-Authenticate: description: Always `Bearer`. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The key can't do this: a read-only key writing, or `Phonely-Organization` naming another org. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The resource doesn't exist, or belongs to another organization. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limited. Retry after the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds until the request can be retried. schema: type: integer '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error. Contact support with the request ID. '502': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- `knowledge_processing_failed`: knowledge processing could not finish. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Authentication, authorization or another required service is temporarily unavailable. security: - HTTPBearer: [] components: schemas: KnowledgeSourceCreate: additionalProperties: false properties: content: description: The document text in Markdown. Empty text is allowed. maxLength: 2000000 title: Content type: string name: description: The document name, 1–255 characters after trimming. maxLength: 255 minLength: 1 title: Name type: string type: const: document description: Create a text document. Files and websites have separate routes. title: Type type: string required: - type - name - content title: KnowledgeSourceCreate type: object KnowledgeSource: additionalProperties: false description: >- Something an agent knows: a document, an uploaded file or a website page. properties: agent_id: description: The agent it belongs to. title: Agent Id type: string content: anyOf: - type: string - type: 'null' description: >- The text the agent uses, in Markdown. `null` when there is none, as for most uploaded files. title: Content id: description: The knowledge source's ID. title: Id type: string is_active: description: >- Whether the agent uses it on calls. A source can be turned off without deleting it. title: Is Active type: boolean name: anyOf: - type: string - type: 'null' description: The name shown in the web app. `null` when it has none. title: Name object: const: knowledge_source default: knowledge_source description: The type of this object, always `knowledge_source`. title: Object type: string type: description: >- `document` is text written in the web app, `file` an uploaded file, `website` a scraped web page. Known values: `document`, `file`, `website`. More can be added, so handle values you don't recognize. title: Type type: string x-extensible-enum: - document - file - website url: anyOf: - type: string - type: 'null' description: The page's address, for a `website`. `null` for other types. title: Url required: - object - id - agent_id - type - name - is_active - url - content title: KnowledgeSource type: object ErrorResponse: additionalProperties: false description: The body of every `/v1` error. properties: error: $ref: '#/components/schemas/Error' description: What went wrong. required: - error title: ErrorResponse type: object Error: additionalProperties: false properties: code: description: >- What went wrong, stable and machine-readable. Known values: `validation_failed`, `invalid_cursor`, `invalid_api_key`, `invalid_user_token`, `user_unavailable`, `insufficient_access`, `organization_mismatch`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `agent_limit_reached`, `agent_too_large`, `sms_setup_required`, `opportunity_analysis_not_set_up`, `precondition_failed`, `payload_too_large`, `unsupported_media_type`, `precondition_required`, `rate_limited`, `internal_error`, `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`, `gateway_timeout`. More can be added, so handle values you don't recognize. title: Code type: string x-extensible-enum: - validation_failed - invalid_cursor - invalid_api_key - invalid_user_token - user_unavailable - insufficient_access - organization_mismatch - forbidden - not_found - method_not_allowed - conflict - agent_limit_reached - agent_too_large - sms_setup_required - opportunity_analysis_not_set_up - precondition_failed - payload_too_large - unsupported_media_type - precondition_required - rate_limited - internal_error - knowledge_processing_failed - bad_gateway - service_unavailable - gateway_timeout details: description: One entry per problem field. Empty when the error has none. items: $ref: '#/components/schemas/ErrorDetail' title: Details type: array message: description: For people. Wording can change; branch on `code`. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: Also in the `X-Request-Id` header. Quote it to support. title: Request Id required: - code - message - details - request_id title: Error type: object ErrorDetail: additionalProperties: false properties: field: description: >- The field the issue is about, as sent: `agent_id`, `limit`. Empty when none. title: Field type: string issue: description: >- What is wrong with the field. Known values: `required`, `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`, `out_of_range`, `invalid_cursor`, `read_only_field`. More can be added, so handle values you don't recognize. title: Issue type: string x-extensible-enum: - required - unknown_field - invalid_json - invalid_type - invalid_value - out_of_range - invalid_cursor - read_only_field message: description: 'For people: what is wrong with this field.' title: Message type: string required: - field - issue - message title: ErrorDetail type: object securitySchemes: HTTPBearer: description: 'An org API key: `Authorization: Bearer phk_…`' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.