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 parameter | Description |
kind | Event 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_id | Only events of this project. |
status | Workflow status, for example submitted, pm_review, rfi_created, claim_potential, sent_to_payment, closed. |
limit | Default 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:
| Key | Meaning |
parameter | What was measured, for example Asphalt binder content (%), Air voids (%), VMA (%), In-place density, cores (% Gmm). |
value | The measured result (number). |
unit | Unit label, for example % or % Gmm. |
target, lcl, ucl | Target and lower / upper control limit, each possibly null. |
lot | Lot label, or null. |
dec | Decimal places to display. |
source | Where it came from: manual, pdf, image, ticket, qa (agency acceptance) or plant (pushed from the asphalt plant). |
category, doc_id, doc, sample_id, page | Present 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_spec | Present 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
| Field | Meaning |
items | The schedule lines, ordered by line_no. |
locked | true once the project has pay estimates: from then on quantities and prices change only through change orders. |
original_value_usd | Contract value at award (sum of original_amount_usd). |
current_value_usd | Current 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 parameter | Description |
project_id | Only documents attached to this project. |
limit | Default 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);
}