Docs
Sign inStart free

Files

Guest and registered free credentials can upload a scanned input file before conversion. Free storage allows 2 MiB per upload, 5 retained files and 10 MiB in total. Files remain owned by the canonical guest or OAuth principal that created them; another guest credential or connection cannot read them. Guest files have no project, and their access ends on credential revocation, expiry or account claim. Retention and active operation pins still govern physical deletion. Free file downloads allow 10 requests per minute and do not debit paid credits.

The preview Files API stores short-lived, private inputs for asynchronous file conversion and connected-drive uploads/replacements. It is available to free credentials and all paid plans and uses api:files:read and api:files:write. File IDs start with fil_; storage paths are never public.

POST/v1/files

Send multipart/form-data with exactly one file and optional project_id, retention_hours (24–720, default 72), and filename. An Idempotency-Key is required. HTTP 202 includes Location, Retry-After: 5, and next_check_at. Uploads use the high-risk rate profile: Free 2, Starter 10, Pro 60 and Scale 240 requests per minute. This is not an independent upload allowance: Files requests share a family counter per credential fingerprint and client IP. Earlier file reads can exhaust the upload allowance; HTTP 429 creates no file and schedules no scan. Existing storage, ownership and scanning rules still apply. Uploads accept sniffed UTF-8 text, Markdown, HTML, CSV, TSV, PDF, Word (DOCX, DOC), Excel (XLSX, XLS), PowerPoint (PPTX, PPT), OpenDocument (ODT, ODS, ODP), RTF and EPUB. Starter and Pro permit 25 MiB, 500 retained files, and 5 GiB; Scale permits 100 MiB, 5,000 files, and 50 GiB. Extension and submitted content type are hints; Chab rejects invalid UTF-8, embedded NUL bytes, encrypted documents, executable/archive content, and extension/content mismatches.

curl -X POST https://www.chab.ai/v1/files \
  -H "Authorization: Bearer $CHAB_API_KEY" \
  -H "Idempotency-Key: upload-contract-v3" \
  -F "[email protected]" \
  -F "project_id=42" \
  -F "retention_hours=72"

New files begin as scan_pending. Poll the Location resource until it becomes available, scan_failed, quarantined, expired, or deletion_pending. Compressed documents must also fit Chab's 100 MiB total scan limit, which includes contained files. A document that exceeds this limit is quarantined even if its uploaded size fits your plan. An inconclusive scan, including a scanner timeout, can instead end in scan_failed after retries. Split large documents before uploading them. Chab checks that its scanner answers before accepting an upload. If it is unavailable, the upload is rejected before publication; a scanner failure after an accepted upload can still end in scan_failed after retries. An unavailable scanner returns HTTP 503 with operation_family_degraded and a Retry-After hint. You can retry that refused request with the same idempotency key.

GET/v1/files

Lists visible files with visibility, project_id, state, created_after, and created_before filters. Every file remains scoped to the API credential that uploaded it. Project files also require a current grant for that project; files without a project are visible only to the uploading credential.

GET/v1/files/{file_id}

Returns trusted metadata and a download URL only while available.

GET/v1/files/{file_id}/download

Streams bytes only while the file is available. Starter allows 30 downloads per minute; Pro allows 60 downloads per minute. Starter and Pro allow 2 concurrent downloads per principal; Scale allows 240 per minute and 8 concurrent downloads. Chab-streamed bytes use metered egress accounting.

DELETE/v1/files/{file_id}

Deletion waits for operation pins and legal holds. A safe tombstone makes an exact retry idempotent for 24 hours. Access to this deletion receipt follows the original uploading credential, with the current project grant still required for project files. Completed deletion returns 200 with state: deleted. A 202 response means deletion remains pending; poll its Location until the file disappears (404), or repeat DELETE for the deletion receipt. New reads and operation pins are denied as soon as expiry or deletion begins, while existing pins keep bytes until their operation reaches a defined terminal outcome.

Conversion accepts file_id or an eligible operation artifact_id. Estimates inspect metadata only; workers require the durable pin before opening bytes. Drive upload/replacement also accepts file_id, or artifact_id with role drive_export. Project files must belong to the current API credential and the target project; files without a project also remain scoped to the uploading credential. See Drive Endpoints. Trusted sources larger than the effective 2 MiB Free, 25 MiB Starter/Pro or 100 MiB Scale ceiling return HTTP 422 source_too_large in both estimates and live starts. Scale callers may set domain backlinks output_format=csv|json for one complete protected backlinks_bulk_export; omitting it preserves automatic JSONL export.

curl https://www.chab.ai/v1/files -H "Authorization: Bearer $CHAB_API_KEY"
curl https://www.chab.ai/v1/files/fil_example -H "Authorization: Bearer $CHAB_API_KEY"
curl -L https://www.chab.ai/v1/files/fil_example/download -H "Authorization: Bearer $CHAB_API_KEY" -o contract.pdf
curl -X DELETE https://www.chab.ai/v1/files/fil_example -H "Authorization: Bearer $CHAB_API_KEY" -H "Idempotency-Key: delete-fil-example"

File errors

file_quota_exceeded means the team reached its retained file count or byte limit. Expired, deletion-pending, pinned, and legally held files continue to count until their bytes are physically purged. Delete files that are no longer needed, wait for eligible deletions to complete, or move to a larger plan.

Type or extension mismatches return unsupported_file_type. Source state errors distinguish scanning, expiry, and deletion states; unauthorized or cross-team file IDs return not_found without disclosing their existence.