Esc

↑↓ move↵ openIndex · Pagefind
API preview · design draft
API reference

One API. Every object on the job.

A resource-oriented REST API over the same record your PMs and accountants use. This is a design draft: nothing is live, every shape is open to change, and founding contractors are shaping it with us.

API preview · design draftSubject to changeRequest early access →

Conventions

Base URL

https://api.os.construction/v1. HTTPS only. JSON in, JSON out.

IDs

Every object has a stable, prefixed id: prj_24118, co_14, inv_4471. Safe to store.

Money

Integer cents with a currency. 8640000 is $86,400.00. No floats near a ledger.

Audit trail

Every object links to an append-only history: who, what, when, and the before/after.

Idempotent writes

Every POST and PATCH takes an Idempotency-Key. Retry freely; we write once.

Versioning

Dated versions pinned per key. Breaking changes ship as a new version, never in place.

Objects

Twelve resources, one data model. A change order points at its RFI, its cost codes and the pay app that billed it, so you never stitch exports together again.

Core

Projectsprj_

A job. Every other object hangs off a project, so one ID gets you the whole record: budget, commitments, changes, billing.

GETGETPATCH

Job cost

Cost codescc_

The spine of job cost. CSI-style codes per project, shared by budgets, commitments, invoices and change orders.

GETPOST
Budgetsbud_

One budget line per project and cost code. Original, approved changes, committed, actual and cost-to-complete in one row.

GETPATCH
Commitmentscmt_

Subcontracts and purchase orders. Invoices draw them down; anything over the remaining balance raises an exception.

GETGETPOST

Changes

Change ordersco_

Priced scope changes. Approval flows straight into budget, commitments, the next pay app and the forecast. One write, everything updates.

GETGETPOSTPOSTGET

Accounting

Invoices (AP)inv_

Vendor bills. Coded to cost codes and commitments, checked against remaining balance, held for retainage.

GETGETPOSTPATCH
Pay appspa_

Owner billings in AIA G702/G703 shape. Approved change orders land on the next pay app automatically.

GETGETPOST
Lien waiverslw_

Conditional and unconditional, progress and final. Tracked per vendor per pay app so nothing gets paid blind.

GETPATCH

Field

RFIsrfi_

Questions with a clock. Linked to the daily log that raised them and the change order they cause.

GETPOST
Daily logsdl_

What happened on site today: crews, hours, weather, notes, photos. Where most RFIs and change orders start.

GETPOST

Agents

Agent actionsact_

The approval queue. Agents propose; people decide. Any action that moves money or crosses a threshold waits here for a human.

GETPOSTPOST

Platform

Webhook endpointswe_

Where we send events. Subscribe to the state changes you care about; every delivery is signed.

POSTGETDELETE

Pagination

List endpoints return a list object. Pass next_cursor back as cursor until has_more is false. Cursors are stable under concurrent writes, so a nightly sync never skips a row.

Expanding

Related objects come back as IDs. Ask for them inline with expand[], up to two levels deep.

list object
{
  "object": "list",
  "url": "/v1/rfis",
  "has_more": true,
  "next_cursor": "cur_9f2c",
  "data": [ { "id": "rfi_212", "object": "rfi", ... } ]
}
curl
curl "https://api.os.construction/v1/change-orders/co_14?expand[]=source_rfi&expand[]=pay_app" \
  -H "Authorization: Bearer $OS_API_KEY"

Errors

Conventional HTTP status codes, plus a machine-readable code and a sentence a PM could read.

  • 400
    invalid_request
    Missing or malformed parameter.
  • 401
    unauthenticated
    No key, or a revoked key.
  • 403
    forbidden
    Key lacks the scope or role. Agent keys hitting approve endpoints land here.
  • 404
    not_found
    No such object, or not visible to this key.
  • 409
    conflict
    State does not allow it (e.g. approving a void CO) or idempotency key reused with a different body.
  • 422
    validation_failed
    Business rule failed: CO lines must sum to amount, period already locked.
  • 429
    rate_limited
    Slow down. See Retry-After.
Error · 422
{
  "error": {
    "type": "invalid_request",
    "code": "exceeds_commitment",
    "message": "Invoice amount exceeds PO-118 remaining commitment by $6,150.00.",
    "param": "amount",
    "object": "inv_4471",
    "request_id": "req_8XkQ2"
  }
}

All endpoints