Esc

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

Projects

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

Design draftSubject to changeobject: projectid prefix: prj_
  1. OBJECT The project object
  2. GET /v1/projectsList projects
  3. GET /v1/projects/{id}Retrieve a project
  4. PATCH /v1/projects/{id}Update a project

The project object

Every object carries an id, timestamps, and an audit_trail. Money is integer cents. Expand any node in the explorer to see how it links to the rest of the record.

  • id
    string
    Unique, stable identifier. Prefixed by object type.
  • object
    string
    String naming the object type.
  • number
    string
    Your job number, e.g. 24-118.
  • name
    string
    Display name.
  • status
    enum
    bid · active · closeout · closed.
  • contract_amount
    integer
    Original contract, cents.
  • approved_changes
    integer
    Sum of approved change orders, cents.
  • revised_contract
    integer
    contract_amount + approved_changes.
  • cost_to_date
    integer
    Posted job cost, cents.
  • percent_complete
    number
    Cost-to-cost percent complete.
  • projected_margin_pct
    number
    Forecast margin at completion.
  • retainage_pct
    number
    Default retainage held on billings.
  • created_at
    timestamp
    ISO 8601, UTC.
  • updated_at
    timestamp
    ISO 8601, UTC. Changes on every write.
  • audit_trail
    string
    Path to the append-only history of who changed what, and when.
project · sample data
object{17}
  • id"prj_24118"id
  • object"project"string
  • number"24-118"string
  • name"Riverside Medical Center — Phase 2"string
  • status"active"string
  • owner"own_riverside_health"id
  • contract_amount4820000000integer$48,200,000.00
  • approved_changes110000000integer$1,100,000.00
  • revised_contract4930000000integer$49,300,000.00
  • cost_to_date3170000000integer$31,700,000.00
  • percent_complete66integer
  • projected_margin_pct11.4number
  • retainage_pct10integer
  • currency"usd"string
  • created_at"2026-01-12T15:04:00Z"timestamp
  • updated_at"2026-09-30T21:18:42Z"timestamp
  • audit_trail"/v1/projects/prj_24118/audit"string
GET /v1/projects

List projects

Returns projects you can see, newest first.

Parameters

  • status
    enumquery
    Filter by status.
  • limit
    integerquery
    Page size, 1 to 100. Default 25.
  • cursor
    stringquery
    Cursor from a previous page’s next_cursor.

Returns

A paginated list of project objects. Errors use the standard error shape.

Request
curl https://api.os.construction/v1/projects \
  -H "Authorization: Bearer $OS_API_KEY"
Response · 200
{
  "object": "list",
  "url": "/v1/projects",
  "has_more": true,
  "next_cursor": "cur_9f2c",
  "data": [
    {
      "id": "prj_24118",
      "object": "project",
      "number": "24-118",
      "name": "Riverside Medical Center — Phase 2",
      "status": "active",
      "owner": "own_riverside_health",
      "contract_amount": 4820000000,
      "approved_changes": 110000000,
      "revised_contract": 4930000000,
      "cost_to_date": 3170000000,
      "percent_complete": 66,
      "projected_margin_pct": 11.4,
      "retainage_pct": 10,
      "currency": "usd",
      "created_at": "2026-01-12T15:04:00Z",
      "updated_at": "2026-09-30T21:18:42Z",
      "audit_trail": "/v1/projects/prj_24118/audit"
    }
  ]
}
GET /v1/projects/{id}

Retrieve a project

One project with live rollups.

Parameters

  • id
    stringpathrequired
    The project ID, e.g. prj_24118.

Returns

The project object. Errors use the standard error shape.

Request
curl https://api.os.construction/v1/projects/prj_24118 \
  -H "Authorization: Bearer $OS_API_KEY"
Response · 200
{
  "id": "prj_24118",
  "object": "project",
  "number": "24-118",
  "name": "Riverside Medical Center — Phase 2",
  "status": "active",
  "owner": "own_riverside_health",
  "contract_amount": 4820000000,
  "approved_changes": 110000000,
  "revised_contract": 4930000000,
  "cost_to_date": 3170000000,
  "percent_complete": 66,
  "projected_margin_pct": 11.4,
  "retainage_pct": 10,
  "currency": "usd",
  "created_at": "2026-01-12T15:04:00Z",
  "updated_at": "2026-09-30T21:18:42Z",
  "audit_trail": "/v1/projects/prj_24118/audit"
}
PATCH /v1/projects/{id}

Update a project

Change name, status or default retainage. Money rollups are computed and read-only.

Idempotent. Send an Idempotency-Key; retries within 24 hours return the original result and never write twice.

Parameters

  • id
    stringpathrequired
    The project ID, e.g. prj_24118.
  • Idempotency-Key
    stringheaderrequired
    Any unique string. Replays return the first result instead of writing twice.
  • status
    enumbody
    New status.

Returns

The project object. Errors use the standard error shape.

Request
curl -X PATCH https://api.os.construction/v1/projects/prj_24118 \
  -H "Authorization: Bearer $OS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closeout"
  }'
Response · 200
{
  "id": "prj_24118",
  "object": "project",
  "number": "24-118",
  "name": "Riverside Medical Center — Phase 2",
  "status": "closeout",
  "owner": "own_riverside_health",
  "contract_amount": 4820000000,
  "approved_changes": 110000000,
  "revised_contract": 4930000000,
  "cost_to_date": 3170000000,
  "percent_complete": 66,
  "projected_margin_pct": 11.4,
  "retainage_pct": 10,
  "currency": "usd",
  "created_at": "2026-01-12T15:04:00Z",
  "updated_at": "2026-09-30T21:18:42Z",
  "audit_trail": "/v1/projects/prj_24118/audit"
}

Events

Webhooks fire on every state change of a project.

project.createdproject.updated