Developers

Your project data, one API call away.

A REST/JSON API for RBCopilot, authenticated with API tokens your company admin creates. Pull projects, QC readings, issues, inspections, material tickets, contract items and pay estimates into your own reports, dashboards and systems.

Overview

The RBCopilot API is a REST API that speaks JSON over HTTPS. Every request goes to one base URL:

https://rbcopilot.com/api/v1

Everything you read or write is scoped to the company that owns the token. A token can never see another company’s data: a resource that belongs to someone else behaves exactly like one that does not exist (404).

Conventions used throughout this page:

  • Requests and responses are application/json. Send Accept: application/json.
  • Timestamps are ISO 8601 strings in UTC. Parse them with a tolerant parser: an explicit +00:00 suffix may or may not be present.
  • Identifiers (id, project_id, …) are opaque UUID strings. Money fields end in _usd and are plain numbers in US dollars.
  • List endpoints return a bare JSON array, newest first. The exceptions are called out per endpoint.
  • This reference covers the most useful read endpoints. Tokens with write scope can also create, update and delete on the same resource paths, subject to the same business rules the app enforces (for example, only a draft pay estimate can change).

Authentication

The API authenticates with API tokens. A company admin creates them inside the app:

  1. Sign in as a company admin and open My account.
  2. Find the API tokens card and choose Create.
  3. Pick a name (for example “Power BI nightly”) and a scope:
    • read — GET requests only.
    • write — read, plus create / update / delete, with the creating admin’s permissions.
  4. Copy the token. It is shown exactly once.

Token format

Tokens look like rbc_live_ followed by 43 URL-safe characters. Only a SHA-256 hash of the token is stored on our side, so it cannot be shown again or recovered. Copy it straight into a secret store.

rbc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sending the token

Send it as a Bearer token on every request:

Authorization: Bearer rbc_live_...
curl -sS https://rbcopilot.com/api/v1/projects \
  -H "Authorization: Bearer $RBC_TOKEN"

What a token can and cannot do

  • Read scope tokens get 403 on any POST, PUT, PATCH or DELETE, and act with a read-only role. Company-wide secrets such as connection keys and the join code are omitted from responses for every API token, read or write.
  • A token stops working (401) when it is revoked, or when the admin who created it is deactivated, removed from the company, no longer an admin, changes or resets their password, or uses sign out of all devices.
  • The app shows each token’s last_used_at so you can spot unused or unexpected tokens.
  • API tokens can not call these areas; they return 403:
    • /auth/* — sign-in, password and two-factor endpoints
    • /company/api-tokens — token management itself
    • /company/export — the full company data export
    • member role changes
    • join-code rotation
    • Field / Plant connection keys and Field device keys
Not every account has every module. Some endpoints (for example material tickets under /operations) are available only when the module is enabled for your company. See Errors for the 402 response.

Errors

Errors use standard HTTP status codes and a JSON body with a detail field (a string, or a list of validation problems for 422).

StatusMeaning
401Missing, invalid or revoked token. Body: {"detail": "Authentication required"} with a WWW-Authenticate: Bearer header.
402The module behind this endpoint is not enabled for your company. The X-Locked-Feature response header names it (for example operations). Ask your administrator to activate it.
403Not allowed: a read-scope token on a write request, a role that lacks permission, or an endpoint API tokens cannot use (see Authentication).
404The resource does not exist or belongs to another company.
422Validation failed: a query parameter or body field has the wrong type or format.
429Rate limited. Wait for the number of seconds in the Retry-After response header, then retry. See Rate limits.

Write requests can also return 400 or 409 when a business rule blocks the change (for example editing a pay estimate that has already been submitted).

Example: 402 (module not enabled)
HTTP/1.1 402 Payment Required
X-Locked-Feature: operations
Content-Type: application/json

{"detail": "This account does not have the 'operations' module enabled. Contact your administrator to activate it."}

Rate limits & result caps

There is no general per-token request quota today. Ordinary read requests are not counted against a limit. Rate limiting is applied to specific sensitive or costly operations, using fixed time windows:

OperationLimit
Sign-in (per IP / per IP + email)60 per 5 min per IP; 10 per 5 min per IP and email
Two-factor sign-in code (per IP / per user)30 per 5 min per IP; 8 per 5 min per user
Join a company with a code (per IP)10 per 15 min
Create an account (per IP)10 per hour
Change password (per IP / per user)60 per 5 min per IP; 10 per 5 min per user
Password-reset link (per IP, and per issuing admin)10 per 15 min per IP; 30 per hour per admin
Unlock paid AI features (per IP and per user)10 per 15 min
Paid AI calls30 per user per hour, and 200 per company per day (platform defaults)
Public demo-request form (per IP)5 per hour

The sign-in, join, account and password operations are not available to API tokens at all (/auth/* returns 403); they are listed so the full picture is clear. The AI quotas apply to the AI endpoints that spend the platform’s model budget, which are not part of this reference. When any limit is hit the API answers 429 with a Retry-After header (seconds until the current window ends).

Be a good citizen. Handle 429 by sleeping for Retry-After and retrying, and keep request rates reasonable: for a scheduled sync, poll no more than once a minute, and fetch only what you need using filters and limit. Limits may be tightened or extended without notice.

Result caps and ordering

List endpoints are capped. There is no offset or cursor: every list returns the most recent rows first, ordered by created_at descending. To go deeper, narrow the request with the filters each endpoint offers (project_id, kind, status) and raise limit where it exists.

EndpointCap
/eventslimit default 500, maximum 5000 (values outside 1–5000 are clamped)
/documentslimit default 100, maximum 500 (clamped to 1–500)
/projectsThe 100 most recent projects; no limit parameter
/issues, /inspections, /pay-estimates, /operations/ticketsThe 200 most recent rows; no limit parameter
/projects/{project_id}/contract-itemsThe whole schedule of items, ordered by line_no
/pay-estimates/{id}/summaryOne estimate, all lines

Endpoint reference

All paths are relative to https://rbcopilot.com/api/v1. Example values are illustrative South Carolina DOT paving data; the field names are exactly what the API returns. Unless noted, a field that is not set comes back as null.

GET /projects

Your company’s projects, newest first (up to 100).

Module: noneQuery parameters: none
Example response
[
  {
    "id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "company_id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
    "name": "I-26 Resurfacing, Exit 85 to Exit 101",
    "code": "SCDOT-I26-2026-014",
    "agency": "SCDOT",
    "spec_id": "scdot-2025",
    "station_start": "STA 100+00",
    "station_end": "STA 880+00",
    "status": "active",
    "metadata_json": null,
    "field_job_id": null,
    "source": null,
    "atp_job_id": null,
    "address": "I-26 EB, Lexington County, SC",
    "lat": 33.9921,
    "lng": -81.2437,
    "ntp_date": "2026-05-04",
    "contract_days": 180,
    "day_type": "working",
    "ld_per_day_usd": 2500.0,
    "substantial_completion_date": null,
    "non_working_dates": ["2026-05-25", "2026-07-03"],
    "count_ntp_day": false,
    "adjustment_cap_usd": null,
    "closeout_reopened_at": null,
    "closeout_reopened_by": null,
    "closeout_reopen_reason": null,
    "created_at": "2026-04-22T15:08:41.220000",
    "created_by": "3c7d9e52-8a14-4b60-b2f9-5d0e1a6c4f87"
  }
]

Use status (planning, active or closed) to filter on your side. The id is what every other endpoint calls project_id.

GET /events

The universal field-event record: field issues, force-account work, weather delays, daily reports and QC readings all live here, distinguished by kind. Filter with kind=qc_test to read QC test readings (the data behind the Asphalt QC charts and the lot pay-factor calculation).

Module: noneNewest first
Query parameterDescription
kindEvent kind, for example qc_test, qc_document, qc_jmf, field_issue, verbal_instruction, force_account, weather_delay, material_ticket, daily_report, crews_hours, photo, rfi, other.
project_idOnly events of this project.
statusWorkflow status, for example submitted, pm_review, rfi_created, claim_potential, sent_to_payment, closed.
limitDefault 500, maximum 5000. Must be an integer or the request fails with 422.

QC readings (kind = qc_test)

A QC reading is an ordinary event whose description is a JSON string holding the measurement. Parse it with json.loads / JSON.parse. Readings are always division: 400 (asphalt). The keys inside description:

KeyMeaning
parameterWhat was measured, for example Asphalt binder content (%), Air voids (%), VMA (%), In-place density, cores (% Gmm).
valueThe measured result (number).
unitUnit label, for example % or % Gmm.
target, lcl, uclTarget and lower / upper control limit, each possibly null.
lotLot label, or null.
decDecimal places to display.
sourceWhere it came from: manual, pdf, image, ticket, qa (agency acceptance) or plant (pushed from the asphalt plant).
category, doc_id, doc, sample_id, pagePresent on readings saved from a QC document: category (asphalt), the id and file name of the source document, the lab sample id and the page. A reading from a plant ticket may also carry ticket_id.
pay_factor, in_specPresent on lot results pushed from the plant.

Not every key is on every reading, so read them defensively. The event’s own occurred_at is when the sample was taken, and station is the location when one was recorded.

Example response (GET /events?kind=qc_test&project_id=8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58&limit=1)
[
  {
    "id": "f06a1b84-93c7-4e2d-8b15-a7d4c9e03f61",
    "company_id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
    "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "number": "EVT-214",
    "kind": "qc_test",
    "title": "Asphalt binder content (%) · Lot 7",
    "description": "{\"parameter\": \"Asphalt binder content (%)\", \"value\": 5.41, \"unit\": \"%\", \"target\": 5.4, \"lcl\": 5.04, \"ucl\": 5.76, \"lot\": \"Lot 7\", \"dec\": 2, \"category\": \"asphalt\", \"source\": \"pdf\", \"doc_id\": \"2b9d5e17-60a3-4c88-91fe-d3a7048b5c12\", \"doc\": \"lot7-ignition-oven.pdf\", \"sample_id\": \"S-0714\", \"page\": 1}",
    "occurred_at": "2026-09-14T14:05:00",
    "created_by_role": "qc",
    "responsible_party": null,
    "inspector_dot": null,
    "station": "STA 412+50",
    "work_front": null,
    "division": 400,
    "activity": null,
    "pay_item": null,
    "crew": null,
    "equipment": null,
    "labor_hours": null,
    "equipment_hours": null,
    "material": null,
    "ticket_no": null,
    "quantity": null,
    "unit": null,
    "supplier": null,
    "cost_impact_usd": null,
    "schedule_impact_days": null,
    "severity": "low",
    "photos_json": null,
    "lat": null,
    "lng": null,
    "status": "submitted",
    "status_history": [
      {"status": "submitted", "at": "2026-09-14T16:22:09.418000", "note": "QC document intake"}
    ],
    "pm_decision": null,
    "pm_notes": null,
    "linked_rfi_id": null,
    "linked_notice_id": null,
    "linked_change_order_id": null,
    "linked_claim_id": null,
    "linked_issue_id": null,
    "linked_pay_estimate_id": null,
    "linked_pay_item_id": null,
    "linked_daily_report_id": null,
    "linked_inspection_id": null,
    "source": null,
    "source_ref": null,
    "created_by": "3c7d9e52-8a14-4b60-b2f9-5d0e1a6c4f87",
    "created_at": "2026-09-14T16:22:09.418000",
    "updated_at": null
  }
]

Events pushed by a connected system carry source (such as plant) and that system’s own source_ref; manually entered ones leave them null.

GET /issues

Project issues (the 200 most recent), each optionally linked to an RFI or a claim.

Module: noneQuery parameters: none

status is one of open, rfi_needed, awaiting_rce, in_progress, resolved, closed; severity is low, med or high.

Example response
[
  {
    "id": "a85c3e29-0d6b-4f71-9c42-e18b7d5a0f36",
    "company_id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
    "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "number": "ISS-038",
    "title": "Unmarked 8-inch water main under proposed milling limits",
    "description": "Potholing at STA 521+30 found a water main 4 inches below the planned milling depth.",
    "division": 200,
    "station": "STA 521+30",
    "status": "rfi_needed",
    "severity": "high",
    "cost_impact_usd": 18500.0,
    "time_impact_days": 2,
    "assigned_to": "R. Whitfield",
    "linked_rfi_id": null,
    "linked_claim_id": null,
    "answer_id": null,
    "created_by": "3c7d9e52-8a14-4b60-b2f9-5d0e1a6c4f87",
    "created_at": "2026-09-09T12:40:15.903000",
    "resolved_at": null
  }
]

GET /inspections

Field inspections (the 200 most recent). checklist_json is a JSON string holding the serialized checklist.

Module: noneQuery parameters: none

status is one of draft, in_progress, submitted, pass, fail, pass_with_corrections.

Example response
[
  {
    "id": "4e1b7c93-a2d5-4086-b3f8-92c6d0a5e714",
    "company_id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
    "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "number": "INS-058",
    "activity": "Tack coat application before surface course",
    "division": 400,
    "section": "401",
    "station": "STA 400+00 to STA 430+00",
    "status": "pass",
    "completion_pct": 100,
    "checklist_json": "[{\"item\": \"Surface clean and dry\", \"ok\": true}, {\"item\": \"Application rate verified\", \"ok\": true}]",
    "performed_by": "T. Alvarez",
    "performed_at": "2026-09-12T13:15:00",
    "answer_id": null,
    "created_at": "2026-09-12T13:20:37.511000"
  }
]

GET /operations/tickets

Material delivery tickets (asphalt mix, aggregate, and so on): the 200 most recent.

Module: operations (402 if not enabled)Query parameters: none

review_status is one of uploaded, needs_review, approved, rejected, disputed, missing_data; ocr_status is none, pending, done or failed. ticket_date is a date string.

Example response
[
  {
    "id": "d3c8e5a1-7f42-4b09-8e6d-1a9b5c2f7d40",
    "company_id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
    "ticket_number": "48213",
    "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "project_name": "I-26 Resurfacing, Exit 85 to Exit 101",
    "ticket_date": "2026-09-14",
    "supplier": "Midlands Asphalt Co.",
    "plant": "Plant 3, West Columbia",
    "material": "Asphalt Mix",
    "mix_type": "SC SM-9.5A",
    "truck_number": "T-27",
    "quantity": 24.35,
    "unit": "TON",
    "temperature_f": 305.0,
    "destination": "STA 412+00 EB",
    "image_url": null,
    "uploaded_by": "QC intake",
    "ocr_status": "done",
    "ocr_confidence": 0.94,
    "review_status": "approved",
    "rejection_reason": null,
    "linked_pay_item_id": null,
    "linked_daily_report_id": null,
    "linked_payment_backup_id": null,
    "linked_qc_test_id": null,
    "created_by": "3c7d9e52-8a14-4b60-b2f9-5d0e1a6c4f87",
    "created_at": "2026-09-14T17:02:44.120000",
    "updated_at": "2026-09-15T09:10:03.774000"
  }
]

GET /projects/{project_id}/contract-items

A project’s contract schedule of items: the master list that pay estimates and change orders work against. Unlike the other lists, the response is an object with the items and project totals.

Module: nonePath parameter: project_id404 for an unknown project
FieldMeaning
itemsThe schedule lines, ordered by line_no.
lockedtrue once the project has pay estimates: from then on quantities and prices change only through change orders.
original_value_usdContract value at award (sum of original_amount_usd).
current_value_usdCurrent contract value including approved change orders (sum of contract_amount_usd).

On each item, pay_basis is unit, lump_sum, allowance or force_account; source is bid, import, manual or change_order; change_orders lists the numbers of the approved change orders that moved the quantity.

Example response
{
  "items": [
    {
      "id": "5f1c9a42-7d3e-4b8a-9a61-0c2e8d4f7b13",
      "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
      "line_no": 1,
      "item_number": "4030340",
      "description": "Hot Mix Asphalt Surface Course, Type B",
      "unit": "TON",
      "contract_qty": 18500.0,
      "original_qty": 18000.0,
      "unit_price_usd": 78.4,
      "pay_basis": "unit",
      "source": "bid",
      "change_order_id": null,
      "changed_by_co": true,
      "change_orders": ["CO-01"],
      "contract_amount_usd": 1450400.0,
      "original_amount_usd": 1411200.0
    },
    {
      "id": "b27e60d1-3a94-4c5f-8e07-91d5a6c3f2e8",
      "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
      "line_no": 2,
      "item_number": "4020010",
      "description": "Cold Planing Bituminous Pavement",
      "unit": "SY",
      "contract_qty": 142000.0,
      "original_qty": 142000.0,
      "unit_price_usd": 2.15,
      "pay_basis": "unit",
      "source": "bid",
      "change_order_id": null,
      "changed_by_co": false,
      "change_orders": [],
      "contract_amount_usd": 305300.0,
      "original_amount_usd": 305300.0
    }
  ],
  "locked": true,
  "original_value_usd": 1716500.0,
  "current_value_usd": 1755700.0
}

GET /pay-estimates

Monthly progress estimates across all projects (the 200 most recent). Use project_id in the response to group them; for the money breakdown of one estimate use the summary endpoint below.

Module: noneQuery parameters: none

status is draft, submitted, approved or paid. retainage_pct is a percentage (5.0 means 5%).

Example response
[
  {
    "id": "c41d7e95-2f08-4a3b-b6d1-3e5f9a07c824",
    "company_id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
    "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "number": "PE-03",
    "period_label": "August 2026",
    "cutoff_date": "2026-08-31T00:00:00",
    "status": "approved",
    "requested_usd": 329403.0,
    "approved_usd": 329403.0,
    "retainage_pct": 5.0,
    "retainage_release_usd": 0.0,
    "period_start": "2026-08-01T00:00:00",
    "notes": null,
    "from_contract": true,
    "approved_net_usd": 329403.0,
    "approved_gross_usd": 346740.0,
    "variance_note": null,
    "is_final": false,
    "final_release_all": false,
    "post_final": false,
    "claim_id": null,
    "negative_net_note": null,
    "created_at": "2026-09-02T14:31:20.640000",
    "submitted_at": "2026-09-03T10:05:12.318000",
    "approved_at": "2026-09-11T16:48:55.092000",
    "paid_at": null
  }
]

GET /pay-estimates/{estimate_id}/summary

Quantities, money and retainage of one estimate: earned to date, previous and this period, per line and in total. Line quantities are cumulative to date. 404 if the estimate does not exist or is not yours.

Module: nonePath parameter: estimate_id

The object has these top-level keys: estimate (header and status), lines, totals, adjustments (price adjustments such as asphalt binder index), warnings (plain-text notices) and disputed (the short-paid amount, when the agency approved less than the computed net). The example below shows a two-line estimate.

Example response
{
  "adjustments": [],
  "estimate": {
    "id": "c41d7e95-2f08-4a3b-b6d1-3e5f9a07c824",
    "number": "PE-03",
    "period_label": "August 2026",
    "project_id": "8a3f2c10-5b7e-4d96-a1c4-6e92b0d73f58",
    "status": "approved",
    "retainage_pct": 5.0,
    "retainage_release_usd": 0.0,
    "cutoff_date": "2026-08-31T00:00:00",
    "submitted_at": "2026-09-03T10:05:12.318000",
    "approved_at": "2026-09-11T16:48:55.092000",
    "paid_at": null,
    "approved_usd": 329403.0,
    "is_latest": true,
    "approved_net_usd": 329403.0,
    "approved_gross_usd": 346740.0,
    "variance_note": null,
    "is_final": false,
    "final_release_all": false,
    "release_computed": false,
    "post_final": false,
    "agency_approved_usd": 329403.0,
    "computed_net_usd": 329403.0,
    "short_paid_usd": 0.0,
    "claim_id": null,
    "claim_number": null,
    "negative_net_note": null,
    "legacy_no_project": false,
    "from_contract": true,
    "previous_estimate": "PE-02",
    "previous_estimate_id": "7a90e3d6-1b58-4c2f-a4e7-d6039f8b1c25"
  },
  "warnings": [],
  "disputed": {"amount_usd": 0.0, "claim_id": null, "claim_number": null},
  "lines": [
    {
      "pay_item_id": "e9b4a7d2-5c10-4f38-86a3-0d7c1e5b9f64",
      "contract_item_id": "5f1c9a42-7d3e-4b8a-9a61-0c2e8d4f7b13",
      "item_number": "4030340",
      "description": "Hot Mix Asphalt Surface Course, Type B",
      "unit": "TON",
      "contract_qty": 18500.0,
      "unit_price_usd": 78.4,
      "qty_previous": 6200.0,
      "qty_this_period": 3600.0,
      "qty_to_date": 9800.0,
      "amount_previous_usd": 486080.0,
      "amount_this_period_usd": 282240.0,
      "amount_to_date_usd": 768320.0,
      "pct_complete": 53.0,
      "overrun": false,
      "reduction": false,
      "note": null,
      "backup_status": "complete",
      "qty_reviewed": true,
      "co_confirm_required": null
    },
    {
      "pay_item_id": "1c6f8d03-b7a9-4e52-90d4-83e2a5f7c1b6",
      "contract_item_id": "b27e60d1-3a94-4c5f-8e07-91d5a6c3f2e8",
      "item_number": "4020010",
      "description": "Cold Planing Bituminous Pavement",
      "unit": "SY",
      "contract_qty": 142000.0,
      "unit_price_usd": 2.15,
      "qty_previous": 90000.0,
      "qty_this_period": 30000.0,
      "qty_to_date": 120000.0,
      "amount_previous_usd": 193500.0,
      "amount_this_period_usd": 64500.0,
      "amount_to_date_usd": 258000.0,
      "pct_complete": 84.5,
      "overrun": false,
      "reduction": false,
      "note": null,
      "backup_status": "complete",
      "qty_reviewed": true,
      "co_confirm_required": null
    }
  ],
  "totals": {
    "earned_to_date_usd": 1026320.0,
    "earned_previous_usd": 679580.0,
    "earned_this_period_usd": 346740.0,
    "retainage_held_previous_usd": 33979.0,
    "retainage_this_period_usd": 17337.0,
    "retainage_released_usd": 0.0,
    "retainage_release_requested_usd": 0.0,
    "retainage_held_to_date_usd": 51316.0,
    "retainage_to_date_usd": 51316.0,
    "adjustments_usd": 0.0,
    "net_this_period_usd": 329403.0,
    "lines_overrun": 0,
    "lines_reduced": 0,
    "lines_missing_backup": 0,
    "short_paid_usd": 0.0,
    "short_paid_to_date_usd": 0.0
  }
}

Net this period is earned this period, minus retainage withheld this period, plus any retainage released, plus price adjustments.

GET /documents

Metadata of the specs, plans, special provisions, reports and other files uploaded to your company, newest first. File contents are not included.

Module: none
Query parameterDescription
project_idOnly documents attached to this project.
limitDefault 100, maximum 500 (values outside 1–500 are clamped).

doc_type is spec, special_provision, plan, report, photo, ticket or misc; status is uploaded, parsing, indexed or failed.

Example response
[
  {
    "id": "90e2b5c8-4d17-4a63-b0f9-2c8a6e1d7b35",
    "filename": "I-26-special-provisions.pdf",
    "doc_type": "special_provision",
    "mime_type": "application/pdf",
    "byte_size": 2481920,
    "page_count": 64,
    "chunk_count": 212,
    "status": "indexed",
    "title": "I-26 Exit 85-101 Special Provisions",
    "summary": "Project-specific special provisions covering milling, surface course, traffic control and liquidated damages.",
    "created_at": "2026-04-23T09:14:02.776000"
  }
]

GET /company

Your company’s profile and plan. Company-wide secrets are never sent to an API token: the connection keys (field_connect_key, plant_connect_key) and the join code are always removed from the response.

Module: noneQuery parameters: none
Example response (read-scope token)
{
  "id": "d9e6b3a7-14c2-4f85-9b30-7a1e5c8d2f64",
  "name": "Palmetto Paving Co.",
  "slug": "palmetto-paving-co",
  "plan": "pro",
  "features": {"compliance": true, "bids": true, "operations": true, "field": true},
  "profile_data": {},
  "field_last_seen_at": null,
  "plant_last_seen_at": "2026-09-15T08:55:31.204000",
  "created_at": "2026-04-20T11:02:09.351000"
}

features shows which modules are enabled, which tells you in advance whether a module-gated endpoint will answer 402.

Examples

curl

Store the token in an environment variable (or better, a secret manager) and never paste it into scripts you commit.

export RBC_TOKEN="rbc_live_..."

# List projects
curl -sS https://rbcopilot.com/api/v1/projects \
  -H "Authorization: Bearer $RBC_TOKEN"

# QC readings for one project (up to 500, newest first)
curl -sS "https://rbcopilot.com/api/v1/events?kind=qc_test&project_id=PROJECT_ID&limit=500" \
  -H "Authorization: Bearer $RBC_TOKEN"

# Contract schedule of items
curl -sS https://rbcopilot.com/api/v1/projects/PROJECT_ID/contract-items \
  -H "Authorization: Bearer $RBC_TOKEN"

# Summary of one pay estimate
curl -sS https://rbcopilot.com/api/v1/pay-estimates/ESTIMATE_ID/summary \
  -H "Authorization: Bearer $RBC_TOKEN"

# Show response headers (useful to inspect Retry-After on a 429)
curl -sS -D - -o /dev/null https://rbcopilot.com/api/v1/projects \
  -H "Authorization: Bearer $RBC_TOKEN"

Python: list projects, then print QC readings

Uses only requests. The helper retries on 429 and honours Retry-After.

import json
import os
import time

import requests

BASE = "https://rbcopilot.com/api/v1"
TOKEN = os.environ["RBC_TOKEN"]          # never hard-code the token

session = requests.Session()
session.headers.update({
    "Authorization": "Bearer " + TOKEN,
    "Accept": "application/json",
})


def get(path, **params):
    """GET a path, retrying when rate limited (429 + Retry-After)."""
    for attempt in range(4):
        r = session.get(BASE + path, params=params, timeout=30)
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", "60"))
            if wait > 300:
                raise RuntimeError("Rate limited for %d s; try again later" % wait)
            time.sleep(wait + 1)
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("Still rate limited after 4 attempts")


projects = get("/projects")
for p in projects:
    print(p["id"], p["code"], p["name"], p["status"])

project = projects[0]
events = get("/events", kind="qc_test", project_id=project["id"], limit=1000)
events.sort(key=lambda e: e["occurred_at"] or e["created_at"])

for e in events:
    try:
        q = json.loads(e["description"] or "{}")
    except ValueError:
        continue                          # no structured reading in this event
    value = q.get("value")
    if value is None:
        continue
    lcl, ucl = q.get("lcl"), q.get("ucl")
    outside = (lcl is not None and value < lcl) or (ucl is not None and value > ucl)
    print("%s  %-42s %s %s  lot=%s%s" % (
        (e["occurred_at"] or "")[:10],
        q.get("parameter", e["title"]),
        value,
        q.get("unit", ""),
        q.get("lot"),
        "  OUTSIDE LIMITS" if outside else "",
    ))

Limiting, polling and handling 429

Because there is no cursor, an incremental sync fetches a bounded window of the newest rows and keeps the ids it has already seen. Poll no more than once a minute.

seen = set()

def new_qc_events(project_id):
    """Newest-first window of QC readings; return only the ones not seen before."""
    events = get("/events", kind="qc_test", project_id=project_id, limit=200)
    fresh = [e for e in events if e["id"] not in seen]
    seen.update(e["id"] for e in fresh)
    return fresh


# First run: pull the whole history once (cap is 5000), then poll gently.
history = get("/events", kind="qc_test", project_id=project["id"], limit=5000)
seen.update(e["id"] for e in history)

while True:
    for e in new_qc_events(project["id"]):
        print("new reading:", e["number"], e["title"])
    time.sleep(60)                        # once a minute is plenty

If a request raises on 429 in your own client, read the header and wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 214

{"detail": "Too many attempts. Try again in a few minutes."}

JavaScript (Node 18+, server-side)

const BASE = "https://rbcopilot.com/api/v1";
const headers = { Authorization: "Bearer " + process.env.RBC_TOKEN };

async function get(path, params = {}) {
  const url = new URL(BASE + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(url, { headers });
    if (res.status === 429) {
      const wait = Number(res.headers.get("retry-after") || 60);
      await new Promise((resolve) => setTimeout(resolve, (wait + 1) * 1000));
      continue;
    }
    if (!res.ok) throw new Error(res.status + " " + (await res.text()));
    return res.json();
  }
  throw new Error("Still rate limited after 4 attempts");
}

const projects = await get("/projects");
const readings = await get("/events", {
  kind: "qc_test",
  project_id: projects[0].id,
  limit: 500,
});
for (const e of readings) {
  const q = JSON.parse(e.description || "{}");
  console.log(e.occurred_at, q.parameter, q.value, q.unit);
}

Security notes

  • Keep tokens server-side. Never put a token in browser code, a mobile app bundle, a public repository or a URL (URLs end up in logs and browser history). Call the API from your own backend and expose only the results you intend to share.
  • Use read scope unless you need writes. A write token acts with the creating admin’s permissions; a leaked one can change or delete project records.
  • Rotate by overlap. Create a new token, deploy it, confirm the new token’s last_used_at moves in My account, then revoke the old one.
  • One token per integration, named after it, so you can revoke a single integration without breaking the others.
  • Revoke immediately if a token may have leaked. Remember that tokens also stop working when their creating admin leaves the company or loses admin rights, so create integration tokens from a long-term admin account.
  • Tokens are only a hash on our side. If you lose one, create a new one; we cannot recover it.
  • Protect the admin account behind your tokens. Turn on two-factor sign-in (any authenticator app, TOTP) in My account for every admin who creates tokens. Tokens themselves don’t ask for a second factor, so treat them like passwords.

Changelog & versioning

v1 is the current version and is part of the base URL (/api/v1). Changes within v1 are additive: new fields, new endpoints and new enum values (such as additional event kind or status values) may appear without notice. Write your client to ignore unknown fields and to tolerate unknown enum values; do not rely on key order or on the exact set of keys.

Breaking changes, if they are ever needed, will ship under a new version prefix rather than altering v1.

Build on RBCopilot

Questions about integrating?

Tell us what you want to connect — your ERP, a BI tool, a plant system — and we will point you to the right endpoints.