---
title: "File a document"
method: POST
path: "/v1/documents"
---

# File a document

`POST /v1/documents`

## Request

- Base URL: `https://app.takibibase.com`
- URL: `https://app.takibibase.com/v1/documents`
- Auth: HTTP bearer

Requires documents:ingest capability. JSON callers send exactly one of text or contentBase64; multipart callers attach file=. Keys file one document per call and spend a daily ask. Refusals (duplicate, empty, oversize, unparseable) return 201 with a refused entry, never an error.

## Request body

- object
  - `name` string, required
  - `text` string
  - `contentBase64` string: File bytes as base64. Exactly one of text or contentBase64.
  - `projectId` string, uuid
  - `folderId` string, uuid

## Response `201`

Stored documents plus refused entries.

- object
  - `documents` Document[], required
    - `id` string, uuid
    - `folderId` string, nullable
    - `name` string
    - `mime` string
    - `bytes` integer
    - `status` string
    - `createdAt` string
    - `ttlDays` integer
    - `stale` boolean
  - `refused` object[], required
    - `name` string
    - `reason` string
    - `code` string: Machine-readable refusal code (IngestError code, or DUPLICATE). Additive: reason text is unchanged.
    - `reasonCode` string: Skip sub-reason (the quality-gate reason, e.g. wrong-language). Present on SKIP_UNRECOVERABLE refusals only.
    - `existingId` string, uuid

## Other responses

- `400`: Invalid request.
- `401`: Missing, invalid, paused or revoked key, or human-only route.
- `403`: Capability or access denied.
- `404`: Resource not found or not visible.
- `429`: Daily budget spent (error.code DAILY_BUDGET_EXCEEDED) or minute throttle (RATE_LIMITED).

---

[API](https://skmtc.dev/takibibase/apis/takibi-agent-api.md) · [All operations](https://skmtc.dev/takibibase/apis/takibi-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/takibibase/apis/takibi-agent-api/revisions/5eacec570cba?raw)