> ## 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. # Get a change ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/underwriting-changes/{change_id} openapi: 3.1.0 info: title: Cactus Partner API version: 1.0.0-draft.1 summary: Document extraction and automated underwriting for CRE. description: | # Overview The Cactus Partner API provides two products: - **Extraction** — upload commercial real estate documents (offering memoranda, rent rolls, T-12 / operating statements, and other business documents) and receive structured, validated JSON with per-field confidence. - **Underwriting** — provide a property address, asset class, and notification email (documents optional) to run a full automated underwriting; results are delivered as a hosted financial-analysis report link plus a machine-readable summary. ## Authentication Every request carries an API key: `Authorization: Bearer ck_live_...` (or `ck_sandbox_...`). Keys are issued by Cactus at kickoff and can be rotated or revoked at any time. ## Products and access Accounts are enabled per product, so not every endpoint below is available to every account: | Product | Endpoints | | --- | --- | | Extraction | `/v1/extractions` | | Underwriting | `/v1/underwritings` | | Usage reporting | `/v1/usage` | `/v1/documents` and `/v1/webhook-endpoints` are available to every account — uploads and webhook delivery underpin both products. Calling an endpoint your account is not enabled for returns `403` with code `product_not_enabled`; contact api@trycactus.com to add a product. A `403` with code `missing_scope` means the account *is* enabled but this particular key was issued without that scope — use a key that carries it. The MCP server advertises only the tools your key can use, so the same rules apply there. ## Sandbox `ck_sandbox_` keys hit the same endpoints but never debit your usage pool: uploads are accepted, and jobs return deterministic fixture output within seconds. Use sandbox keys for integration development and CI. Registering a sandbox document under a documented example filename (e.g. `example-rent-roll-1.xlsx`) returns the real extracted output of that reference document — see the Sandbox guide for the full list. ## Asynchronous jobs Extractions and underwritings are asynchronous. Create the job (`202 Accepted`), then either poll the job resource or register a webhook endpoint to receive signed events (recommended). Typical extraction turnaround is minutes. ## Billing semantics A document is **accepted** when it passes validation (size caps, page/row counts, type resolution). Acceptance debits your usage pool at the fixed rate-card price for the document type — before processing, so pricing is deterministic. Rejected documents are never charged. Documents exceeding their type's size cap bill as multiple units of the same type; the accept response discloses `billed.units`. Files over 500 pages or 100 MB are rejected outright. ## Idempotency All `POST` endpoints accept an `Idempotency-Key` header (any unique string, e.g. a UUID). Retrying a request with the same key returns the original response instead of creating a duplicate. ## Errors Errors follow RFC 9457 (`application/problem+json`) and always include a stable machine-readable `code` and the `request_id` to quote in support requests. ## Versioning The path major version (`/v1`) changes only for breaking API changes. Extraction output schemas are versioned independently per document type (e.g. `rent_roll.v1`) and declared in every result; breaking output changes ship as a new schema version with advance notice and an overlap window. --- All field-level output schemas — `RentRollData` (`rent_roll.v1`), `T12Data` (`t12.v1`), `OfferingMemorandumData` (`offering_memorandum.v1`), and `GenericDocumentData` (`facts.v1`) — are finalized against the extraction engine's real output. contact: name: Cactus API Support email: api@trycactus.com license: name: Proprietary — Cactus API License Agreement identifier: LicenseRef-Cactus-Partner-Agreement servers: - url: https://api.trycactus.com description: Production (live and sandbox keys) security: - apiKey: [] tags: - name: Documents description: Upload and manage documents via presigned URLs. - name: Extractions description: Structured data extraction jobs and results. - name: Underwritings description: Automated underwriting runs. - name: Usage description: Usage pool balance and metered activity. - name: Webhook Endpoints description: Manage endpoints that receive signed event notifications. paths: /v1/underwriting-changes/{change_id}: parameters: - $ref: '#/components/parameters/ChangeId' - $ref: '#/components/parameters/EndUser' get: tags: - Underwritings summary: Get a change operationId: getUnderwritingChange responses: '200': description: The change. content: application/json: schema: $ref: '#/components/schemas/UnderwritingChange' '404': $ref: '#/components/responses/NotFound' components: parameters: ChangeId: name: change_id in: path required: true schema: type: string example: chg_01J9ZK3M EndUser: name: X-Cactus-End-User in: header required: false schema: type: string maxLength: 255 description: | Act for one of your end users (the `end_user_ref` you pass when creating underwritings). Limits every underwriting, document and extraction call to that user's resources. Required on MCP connections once your account serves end users. schemas: UnderwritingChange: type: object required: - id - object - underwriting_id - status - changes - created_at - expires_at - sandbox properties: id: type: string example: chg_01J9ZK3M object: type: string const: underwriting_change underwriting_id: type: string status: type: string enum: - pending - confirmed - expired - failed changes: type: array items: type: object preview: type: object properties: before: type: object after: type: object derived_changes: type: array items: type: object disclosure: type: string note: type: string created_at: type: string format: date-time expires_at: type: string format: date-time confirmed_at: type: string format: date-time sandbox: type: boolean new_underwriting_id: type: string new_underwriting: $ref: '#/components/schemas/Underwriting' Underwriting: type: object required: - id - object - status - created_at - sandbox properties: id: type: string example: uw_01J9ZK3M object: type: string const: underwriting status: $ref: '#/components/schemas/UnderwritingStatus' progress: type: object properties: phase: type: string stage: type: string description: >- The pipeline step in progress — `document_pack`, `market_pack`, `subject_seed`, `financial_mapping`, `underwriting_analysis`, `excel_calculation`, `agent_review`, `recalculation`, `finalizing`, `complete`. Informational only — new steps appear here without a `status` change, so branch on `status`, not on this. detail: type: string property: type: object description: Echo of the submitted property. end_user_ref: type: string description: Echo of the submitted end-user identifier, when one was supplied. version: type: integer description: >- Report version. 1 for a first run; a confirmed change creates a new underwriting with the next number. previous_underwriting_id: type: string description: The version this one changed (absent on version 1). documents: type: array description: Echo of the submitted selection, with each role settled. items: type: object properties: document_id: type: string role: $ref: '#/components/schemas/UnderwritingDocumentRole' options: type: object description: Echo of the submitted options, with defaults applied. billed_total_usd: type: string sandbox: type: boolean created_at: type: string format: date-time completed_at: type: string format: date-time elapsed_seconds: type: integer description: >- Whole seconds since `created_at`. Present while the run is active, so a caller can tell a run that just started from one approaching the 4-hour ceiling without doing date math. example: 640 poll_after_seconds: type: integer description: >- Recommended seconds to wait before polling again. Present while the run is active; mirrors the `Retry-After` header. Prefer this over a hard-coded interval. example: 30 report: type: object description: Present when completed. Private delivery omits url. properties: url: type: string format: uri description: > Present only for public_link delivery. Public link to the underwriting report. Anyone holding it can open it, with no login. It is **live**: it shows the report as it stands whenever someone opens it, so a later correction reaches everyone already sent the link. It does not expire. Access ends by revoking the link, which is why there is no expiry to read here. excel_url: type: string description: >- Path to `GET /v1/underwritings/{id}/model`, which returns a short-lived download URL for the populated Excel model — the workbook behind the report, in a form an analyst can keep working in. example: /v1/underwritings/uw_01J9ZK3M/model summary: type: object description: | Headline metrics as plain numbers, lifted out of `results` for convenience: `value_base_usd`, `cap_rate`, `normalized_noi_usd`, `levered_irr`, `dscr`, `equity_multiple`, `total_units` and so on, plus `readiness_status` and `disclosure_count`. A metric the run could not establish is **absent**, never null — the reason it is missing is in `results`, beside the figure. additionalProperties: true results: type: object description: | The whole report, in the same shape the public report page is rendered from (`broker-public-underwriting-delivery-v1`). Present on a completed run when fetched individually; omitted from list responses and webhook payloads, which would otherwise carry megabytes. Every figure is a `{state, value, reason}` triple, because the product distinguishes a known zero from something it could not establish. `state` is one of `known`, `zero`, `unavailable`, `not_applicable`; when it is not `known` or `zero`, `value` is null and `reason` says why in a sentence you can show a user. Collections carry `{state, items, reason}`, where `state` is `available`, `partial`, `confirmed_empty` or `unavailable` — "we found none" and "we could not look" are different answers. Top level: `schema_version`, `generated_at`, `property`, `chapters`, `critical_assumptions`, `readiness`, `release`. The chapters follow the argument the report makes: `answer` (what it is worth, and the cap rate and NOI behind that), `income` (unit mix and rent comparables), `revenue` (the trailing-twelve income statement and the year-one revenue waterfall), `cost` (the expense statement and the normalizations applied to it), `value` (sale comparables and a cap-rate sensitivity grid), `buyer` (returns, financing and the annual cash-flow table), `risk` (market watch), `next` (talking points). `readiness.disclosures` is the part to surface next to any figure you quote: each names something the run had to assume or could not establish, with copy written to be shown to an end user. `critical_assumptions.items` ranks the assumptions the valuation is most sensitive to, with the dollar and IRR impact of moving each. additionalProperties: true error: type: object properties: code: type: string message: type: string Problem: type: object description: RFC 9457 problem details. required: - title - status - code - request_id properties: type: type: string format: uri description: > Link to this code's entry on the errors page. An anchor, not a path — every code lives on the one page. example: https://docs.trycactus.com/errors#document_over_size_cap title: type: string example: Document exceeds the size limit status: type: integer example: 422 detail: type: string example: Files over 500 pages or 100 MB are rejected and not charged. code: type: string description: Stable machine-readable error code. example: document_over_size_cap request_id: type: string errors: type: array description: Field-level validation errors, when applicable. items: type: object properties: field: type: string code: type: string message: type: string UnderwritingStatus: type: string description: | `queued` → `ingesting` (reading the documents and the market) → `underwriting` (analysis) → `calculating` (the financial model) → `completed`. `progress.stage` carries the finer-grained pipeline step behind each. enum: - queued - ingesting - underwriting - calculating - completed - failed UnderwritingDocumentRole: type: string description: | What a document is *for* in the run. At most one document per role. | Role | Accepted formats | |---|---| | `rent_roll` | PDF, XLS, XLSX, XLSM | | `t12` | PDF, XLS, XLSX, XLSM | | `financial_model` | XLS, XLSX, XLSM | | `offering_memorandum` | PDF | | `supporting` | PDF, XLS, XLSX, XLSM | enum: - rent_roll - t12 - financial_model - offering_memorandum - supporting responses: NotFound: description: Resource does not exist (or belongs to another partner). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: apiKey: type: http scheme: bearer bearerFormat: ck_live_* or ck_sandbox_* description: Partner API key issued by Cactus. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.