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

# Add documents

> Add, replace, and delete searchable documents

Add up to 50 documents at a time. Each document needs your own stable `doc_id` and its source text.

The examples use the environment variables configured in the [quickstart](/quickstart).

```bash theme={null}
curl --fail-with-body \
  "$BREADBOWL_API_URL/v1/indexes/$BREADBOWL_INDEX_ID/documents" \
  -H "Authorization: Bearer $BREADBOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "doc_id": "help-center:refunds",
      "text": "Refund requests are accepted within 30 days.",
      "metadata": {"source": "help-center", "status": "published"}
    }]
  }'
```

## Choose stable IDs

`doc_id` identifies a document within an index. Sending the same ID again replaces the existing document, so use an ID from your source system rather than a title, URL, or content hash.

This replacement behavior also makes an upload safe to repeat after a timeout.

## Check every response

An upload can return HTTP 200 even when individual documents fail:

```json theme={null}
{
  "upserted_documents": 1,
  "failed": [
    {"doc_id": "empty-document", "error": "document produced no chunks"}
  ]
}
```

Only mark a document as complete when its ID is not in `failed`. Correct failed documents before sending them again.

## Limits

* 50 documents per request
* 100 KiB of UTF-8 text per document
* 255 characters per `doc_id`
* 5 MiB for the complete JSON request

Keep metadata small and consistent. Search filters can match top-level string, number, or boolean fields exactly.

## Delete a document

Delete documents when their source records are removed or should no longer be searchable:

```bash theme={null}
curl --fail-with-body -X DELETE \
  "$BREADBOWL_API_URL/v1/indexes/$BREADBOWL_INDEX_ID/documents/help-center%3Arefunds" \
  -H "Authorization: Bearer $BREADBOWL_API_KEY"
```

Deletion is safe to repeat. See the [API reference](/api-reference/overview) for complete request and response schemas.