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

# Quickstart

> Upload a rent roll and get structured data back in five requests.

You'll need an API key — your Cactus contact provides one at kickoff. Use
your sandbox key (`ck_sandbox_...`) for this walkthrough; it returns instant
example results and is never billed. The same requests work unchanged with
your live key.

## 1. Register the document

Tell us the filename, type, and exact size in bytes. The response includes a
short-lived upload URL.

```bash theme={null}
curl -X POST https://api.trycactus.com/v1/documents \
  -H "Authorization: Bearer $CACTUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "rosewood-rent-roll.xlsx",
    "declared_type": "rent_roll",
    "byte_size": 25592
  }'
```

Save `id` (the document id) and `upload.url` from the response.

<Note>
  **Why the exact byte size?** It's built into the upload URL's signature, so
  storage rejects any upload that doesn't match what was registered — and
  files over the size limit are rejected here, before you spend time
  uploading. Your HTTP client already knows the size (it sends it as
  `Content-Length`). The filename's extension tells us how to process the
  file (`.xlsx`/`.xls` are handled natively as spreadsheets). `content_type`
  is optional; when provided it's also pinned into the upload signature.
</Note>

## 2. Upload the file

`PUT` the raw bytes to the upload URL. The upload must match the registered
byte size exactly.

```bash theme={null}
curl -X PUT --data-binary @rosewood-rent-roll.xlsx "$UPLOAD_URL"
```

## 3. Start the extraction

This validates the document and charges its fixed rate before processing —
pricing is always known up front. Rejected documents are never charged.

```bash theme={null}
curl -X POST https://api.trycactus.com/v1/extractions \
  -H "Authorization: Bearer $CACTUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "doc_..."}'
```

The response is `202 Accepted` with an extraction id and the billed amount.

## 4. Wait for completion

Poll the extraction until `status` is `completed` (typically a few minutes
for live documents; instant in sandbox):

```bash theme={null}
curl https://api.trycactus.com/v1/extractions/ext_... \
  -H "Authorization: Bearer $CACTUS_API_KEY"
```

Prefer push? Register a [webhook endpoint](/webhooks) and receive
`extraction.completed` instead of polling.

## 5. Fetch the result

```bash theme={null}
curl https://api.trycactus.com/v1/extractions/ext_.../result \
  -H "Authorization: Bearer $CACTUS_API_KEY"
```

Every result declares its `schema_version` and returns extracted values with
confidence scores and source locations (sheet cell or page), so you always
know where a number came from.

## Check your usage anytime

```bash theme={null}
curl https://api.trycactus.com/v1/usage \
  -H "Authorization: Bearer $CACTUS_API_KEY"
```

Returns your pool balance and period-to-date usage by document type. See
[Billing](/billing) for how the usage pool works.