> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbutter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Document

Create a knowledge base document from a file upload or text content. This triggers an asynchronous processing job to index the content.

<Note>
  This endpoint accepts `multipart/form-data` for file uploads. For text documents, you can use JSON.
</Note>

### Headers

<ParamField header="X-API-Key" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The organization ID.
</ParamField>

### Permissions

* `kb:create` (admin, agent\_manager)

### Request Body (Form Data)

<ParamField body="name" type="string" required>
  The name of the document (1-200 characters).
</ParamField>

<ParamField body="file" type="file">
  The file to upload (e.g., PDF, DOCX, TXT). Required if `text` is not provided.
  <br />Max file size: 50MB
</ParamField>

<ParamField body="text" type="string">
  Raw text content. Required if `file` is not provided.
</ParamField>

<ParamField body="agent_id" type="string">
  Optional agent ID to immediately attach this document to after creation.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable success message.
</ResponseField>

<ResponseField name="data" type="object">
  Created document metadata.

  <Expandable title="properties">
    <ResponseField name="documentation_id" type="string">
      Unique document identifier.
    </ResponseField>

    <ResponseField name="name" type="string">
      Document name.
    </ResponseField>

    <ResponseField name="type" type="string">
      Document type (`file` or `text`).
    </ResponseField>

    <ResponseField name="message_id" type="string">
      SQS message ID for the processing job.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash File Upload theme={null}
  # Using multipart/form-data
  curl -X POST "https://api.getbutter.ai/api/knowledge-base" \
    -H "X-API-Key: <YOUR_API_KEY>" \
    -H "X-Organization-Id: <YOUR_ORG_ID>" \
    -F "name=Product Manual" \
    -F "file=@/path/to/manual.pdf" \
    -F "agent_id=agent_abc123"
  ```
</RequestExample>

<RequestExample>
  ```json Text Document theme={null}
  {
    "name": "FAQ Content",
    "text": "Q: What are your hours? A: We're open 9-5...",
    "agent_id": "agent_abc123"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "File 'manual.pdf' uploaded and processing started",
    "data": {
      "documentation_id": "doc_a1b2c3d4e5f6",
      "name": "Product Manual",
      "type": "file",
      "message_id": "msg_abc123def456"
    }
  }
  ```
</ResponseExample>

### Errors

<ResponseField name="400" type="object">
  Must provide either file or text, not both or neither.
</ResponseField>

<ResponseField name="404" type="object">
  Agent not found (if agent\_id provided).
</ResponseField>