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

# Upload Documents

> Upload one or more documents for processing

## Endpoint

```
POST https://api.documind.cloud/api/v1/upload
```

## Authentication

Requires `extractions:write` scope.

## Request

### Headers

| Header      | Value        | Required |
| ----------- | ------------ | -------- |
| `X-API-Key` | Your API key | Yes      |

### Body

Form data with file uploads:

| Field   | Type | Required | Description                                                 |
| ------- | ---- | -------- | ----------------------------------------------------------- |
| `files` | file | Yes      | One or more files to upload (can repeat for multiple files) |

### Extraction-Compatible File Types

The upload endpoint stores files and returns document IDs. Schema generation and extraction currently process:

* **PDF**: `.pdf`
* **Images**: `.jpg`, `.jpeg`, `.png`, `.tiff`, `.bmp`

Other file types may upload successfully, but schema generation and extraction can fail if the backend cannot convert the file.

### Request Limits

The backend does not enforce a documented per-file or per-request count limit in application code. Infrastructure may still reject oversized requests. For reliability, keep batches small and retry failed upload requests.

## Response

### Success Response (200)

Returns an array of document IDs:

```json theme={null}
[
  "123e4567-e89b-12d3-a456-426614174000",
  "223e4567-e89b-12d3-a456-426614174001"
]
```

## Examples

<CodeGroup>
  ```python Python theme={null}
  import requests

  API_KEY = "your_api_key_here"
  headers = {"X-API-Key": API_KEY}

  # Upload single file
  with open("invoice.pdf", "rb") as f:
      files = {"files": f}
      response = requests.post(
          "https://api.documind.cloud/api/v1/upload",
          headers=headers,
          files=files
      )

  document_ids = response.json()
  print(f"Uploaded document: {document_ids[0]}")

  # Upload multiple files
  files = [
      ("files", open("invoice1.pdf", "rb")),
      ("files", open("invoice2.pdf", "rb")),
      ("files", open("invoice3.pdf", "rb"))
  ]

  response = requests.post(
      "https://api.documind.cloud/api/v1/upload",
      headers=headers,
      files=files
  )

  document_ids = response.json()
  print(f"Uploaded {len(document_ids)} documents")

  # Close files
  for _, f in files:
      f.close()
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');
  const FormData = require('form-data');
  const fs = require('fs');

  const API_KEY = 'your_api_key_here';

  // Upload single file
  const form = new FormData();
  form.append('files', fs.createReadStream('invoice.pdf'));

  const response = await axios.post(
    'https://api.documind.cloud/api/v1/upload',
    form,
    {
      headers: {
        ...form.getHeaders(),
        'X-API-Key': API_KEY
      }
    }
  );

  const documentIds = response.data;
  console.log(`Uploaded document: ${documentIds[0]}`);

  // Upload multiple files
  const multiForm = new FormData();
  multiForm.append('files', fs.createReadStream('invoice1.pdf'));
  multiForm.append('files', fs.createReadStream('invoice2.pdf'));
  multiForm.append('files', fs.createReadStream('invoice3.pdf'));

  const multiResponse = await axios.post(
    'https://api.documind.cloud/api/v1/upload',
    multiForm,
    {
      headers: {
        ...multiForm.getHeaders(),
        'X-API-Key': API_KEY
      }
    }
  );

  console.log(`Uploaded ${multiResponse.data.length} documents`);
  ```

  ```bash cURL theme={null}
  # Upload single file
  curl -X POST https://api.documind.cloud/api/v1/upload \
    -H "X-API-Key: YOUR_API_KEY" \
    -F "files=@invoice.pdf"

  # Upload multiple files
  curl -X POST https://api.documind.cloud/api/v1/upload \
    -H "X-API-Key: YOUR_API_KEY" \
    -F "files=@invoice1.pdf" \
    -F "files=@invoice2.pdf" \
    -F "files=@invoice3.pdf"
  ```
</CodeGroup>

## Error Responses

### 400 Bad Request

Malformed multipart request:

```json theme={null}
{
  "detail": "There was an error parsing the body"
}
```

### 401 Unauthorized

Missing or invalid API key:

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

### 413 Payload Too Large

Infrastructure may reject oversized requests before they reach the backend:

```json theme={null}
{
  "detail": "Request Entity Too Large"
}
```

### 500 Internal Server Error

Server error during upload:

```json theme={null}
{
  "detail": "Failed to upload documents. Please try again later."
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Batch Upload for Efficiency">
    Upload multiple files in a single request instead of making multiple requests. This is faster and more efficient.
  </Accordion>

  <Accordion title="Check File Size Before Upload">
    Validate file sizes client-side to avoid failed uploads and improve user experience.
  </Accordion>

  <Accordion title="Handle Upload Errors">
    Implement retry logic with exponential backoff for failed uploads, especially for large files.
  </Accordion>

  <Accordion title="Store Document IDs">
    Save the returned document IDs; they are required for schema generation and extraction requests.
  </Accordion>
</AccordionGroup>

## Rate Limits

Upload endpoint is subject to rate limits based on your subscription tier. Contact support for higher limits.

## Notes

* Each upload receives a new document ID
* Upload stores the file only; OCR/layout processing runs during schema generation or extraction

## Next Steps

<CardGroup cols={2}>
  <Card title="Extract Data" icon="brain" href="/api-reference/extract">
    Extract structured data from uploaded documents
  </Card>

  <Card title="Generate Schema" icon="wand-magic-sparkles" href="/api-reference/generate-schema">
    Auto-generate extraction schema from document
  </Card>

  <Card title="List Documents" icon="list" href="/api-reference/list-documents">
    View documents with extraction records
  </Card>

  <Card title="Upload Guide" icon="book" href="/api/extraction/upload-documents">
    Detailed upload workflow guide
  </Card>
</CardGroup>