REST API reference.

Base URL Roadmap (S2-gate)

https://api.assets.hoistai.com/v1

This host is not resolvable today. The API will be versioned in the path; we plan to maintain v1 for 12 months after a v2 ships. Breaking changes go to a new version; non-breaking changes (new optional fields, new endpoints) will ship to v1 without notice — code defensively.

Authentication

Two modes. One is live today.

OAuth 2.1 (live for MCP)

Authorisation code + PKCE + Resource Indicators (RFC 8707). RFC 6749 / 7591 Dynamic Client Registration. Live today against the MCP server. Endpoints:

• https://assets.hoistai.com/.well-known/oauth-authorization-server (discovery)
• https://assets.hoistai.com/oauth/register (DCR)
• https://assets.hoistai.com/oauth/authorize
• https://assets.hoistai.com/oauth/token

Planned scopes for S2-gate: search:read, search:write, batch:write, exports:write, billing:read. The MCP server accepts these scopes today against fixture tools.

API key Roadmap (S2-gate)

Authorization: Bearer hoist_live_01HX...

API keys ship at S2-gate from dashboard → API keys (route not live today). Planned scopes: readonly, readwrite, batch. Test keys (hoist_test_…) will be free and fixture-only. Rotation from the dashboard with a 24-hour grace period.

Endpoints Roadmap (S2-gate)

None of the endpoints below are reachable today. They land at S2-gate. The shapes are the contract we're building against.

POST /ppsr/search

Will run a PPSR organisation or serial-number search. Returns the AFSA certificate, the Due Diligence Record, and a record ID.

Body

{
  "search_type": "organisation" | "serial_number",
  "acn": "123 456 789",                  // when search_type=organisation
  "serial_number": "1FUJBBCK87LX73121",  // when search_type=serial_number
  "serial_type": "vin" | "chassis" | "aircraft",
  "reference": "DEAL-2026-0042",         // optional, your deal ID
  "sandbox": false                       // optional
}

Response 200

{
  "record_id": "rec_01HX5F9AB2",
  "search_type": "organisation",
  "target": { "acn": "123 456 789", "name": "ACME Excavations Pty Ltd" },
  "certificate_url": "/v1/certs/cert_01HX...pdf",
  "record_url": "/v1/records/rec_01HX5F9AB2.pdf",
  "record_hash": "sha256:9f4e2c8b...",
  "audit_chain_id": "ac_2026-05-15-0042",
  "results": {
    "registrations_current": 3,
    "registrations_historic": 0,
    "registrations": [ ... ]
  },
  "billed_at": "A$2.50",
  "timestamp": "2026-05-15T03:42:11Z"
}

Planned cost: A$2.50 (live). A$0.00 (sandbox).

POST /ppsr/batch

Will submit a CSV of search inputs and return a job ID. Poll for completion; final response is a signed ZIP of records. Planned limits: 500 rows per CSV on Pro; unlimited on Team.

GET /abn/{abn}

Will verify an ABN. Returns registered name, trading names (current), GST status, ABN status. Planned cost: A$0.10.

GET /abn/{abn}/history

Will return ABN history: trading-name changes, GST registration changes, dates. Planned cost: A$0.10.

GET /gst/{abn}?as_at=YYYY-MM-DD

Will return GST registration status as at a specific date. Useful for tax-period verification. Planned cost: A$0.10.

GET /records/{id}

Will return the record as JSON. Append .pdf for the PDF. Planned cost: free for records on your account.

GET /records/{id}/verify?hash=sha256:...

Will verify a record hash against the audit chain. Returns { "match": true|false, "audit_chain_id": "..." }. Planned cost: free; rate-limited.

GET /records?reference=DEAL-2026-0042

Will list records, filtered by reference, target, date range. Paginated (50 per page, max 200 via ?limit).

POST /exports

Will create an evidence-pack ZIP of records matching a filter. Returns a job ID; webhook fires when ready (Team tier) or poll /exports/{id}.

GET /usage

Will return: { tier, included_allowance_aud, used_aud, overage_aud, period_end }. Useful for dashboards.

Errors Roadmap (S2-gate)

Planned error shape:

{
  "error": "individual_grantor_not_supported",
  "message": "Hoist Assets is org-only: individual-grantor searches are not supported.",
  "documentation_url": "https://assets.hoistai.com/trust/npii-boundary/"
}

Rate limits Roadmap (S2-gate)

• Sandbox keys: unlimited.
• Live keys: 60 requests/minute per key, burst to 120.
• Batch endpoint: 10 jobs/hour per account; talk to us for more.
• 429 responses will include Retry-After (seconds).

Webhooks Roadmap (S2-gate, Team tier)

Subscribe in the dashboard at S2-gate. Payloads will be signed with HMAC-SHA256 using your webhook secret. Verify by computing HMAC of the raw body and comparing to X-Hoist-Signature.

Planned events: search.completed, search.failed, batch.completed, export.ready, billing.overage_threshold_80. Webhook infrastructure is not shipped at S1-gate.

SDKs Roadmap (S2-gate)

Public SDK repositories will be cut at S2-gate. Today none of these install commands resolve.

• TypeScript / Node.js — npm i @hoist-assets/sdk
• Python — pip install hoist-assets
• Ruby — gem install hoist_assets
• Other languages: generate from the OpenAPI spec with openapi-generator once published. Targeting Go, Rust, PHP at S2-gate.