Call the API from typed code.
TypeScript and Python clients for every implemented REST operation, with pagination, idempotency keys, safe retries and webhook signature checks. The same operations are available as one OpenAPI 3.0 document and a Postman collection.
OpenAPI document and Postman collection
openapi.json is every implemented operation in one OpenAPI 3.0 document, generated from the same module contracts as the REST reference. Each operation has a readable operationId, and the x-os-paginated and x-os-idempotent extensions mark list endpoints and writes that accept an Idempotency-Key. Use it with your own code generator, or import it into Insomnia, Bruno or Postman.
os-construction.postman_collection.json is a Postman v2.1 collection with one folder per tool. Import it, then set the collection variables token, companyId and projectId; baseUrl defaults to https://app.os.construction. Writes send Idempotency-Key: {{$guid}}.
Both files are regenerated from the app's contracts whenever the API changes.
TypeScript and Python SDKs
Status: the packages @os-construction/sdk (npm) and os-construction (PyPI) are built and tested, but not published yet. Until they are, the names below will not install from the public registries; the examples show the API they will have. If you need an SDK build before then, contact us.
- Every implemented operation2,549 REST operations generated from the app's API contracts. Only operations the API serves are included, so nothing in the client returns 404 by design.
- TypedTypeScript: path, query, body and response types per operation. Python: one method per operation with typed path parameters, TypedDict models for named schemas, and a py.typed marker; checked with mypy --strict.
- Paginationpaginate() walks every page through the Link next relation; request() returns Total, Per-Page and the links.
- Idempotency keysPass idempotencyKey / idempotency_key, or turn on automatic keys for writes. Retries reuse the same key, and the response says when it was replayed.
- Retries that cannot double a writeNetwork errors, 409, 429 and 502-504 are retried with Retry-After, but only for GET requests and writes that carry a key.
- Webhook verificationChecks X-OS-Signature (HMAC-SHA256 of the raw body) in constant time, supports a list of secrets for rotation, and is tested against vectors produced by the server signer.
Operation names
Names come from the method and path, so you can derive them from the REST reference. Versions other than v1.0 carry a suffix.
listProjectRfislist_project_rfisGET /rest/v1.0/projects/{project_id}/rfisgetProjectRfiget_project_rfiGET /rest/v1.0/projects/{project_id}/rfis/{id}createProjectRficreate_project_rfiPOST /rest/v1.0/projects/{project_id}/rfisadvanceBallInCourtProjectRfiadvance_ball_in_court_project_rfiPATCH …/rfis/{id}/advance_ball_in_courtlistProjectSubmittalsV11list_project_submittals_v11GET /rest/v1.1/projects/{project_id}/submittals
import { OsConstructionClient } from "@os-construction/sdk";
const client = new OsConstructionClient({
token: process.env.OS_ACCESS_TOKEN,
companyId: 1, // sent as OS-Company-Id
autoIdempotencyKey: true, // every write gets a fresh Idempotency-Key
retries: 2, // GETs and keyed writes only
});
// One page, typed path, query and response
const open = await client.call("listProjectRfis", {
path: { project_id: 2 },
query: { "filters[status]": "open", per_page: 50 },
});
// Every page: follows the Link "next" relation
for await (const rfi of client.paginate("listProjectRfis", { path: { project_id: 2 } })) {
console.log(rfi.number, rfi.subject);
}
// Same call as a method
const rfi = await client.ops.getProjectRfi({ path: { project_id: 2, id: 17 } });import os
import os_construction as osc
client = osc.Client(os.environ["OS_ACCESS_TOKEN"], company_id=1,
auto_idempotency_key=True, retries=2)
open_rfis = client.list_project_rfis(2, query={"filters[status]": "open", "per_page": 50})
for rfi in client.paginate("listProjectRfis", path={"project_id": 2}):
print(rfi["number"], rfi["subject"])
rfi = client.get_project_rfi(2, 17)
# async
async with osc.AsyncClient(os.environ["OS_ACCESS_TOKEN"]) as ac:
rfi = await ac.get_project_rfi(2, 17)Verify webhooks
Each delivery carries X-OS-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body with your subscription's signing secret. Verify the raw bytes before parsing JSON, then de-duplicate on X-OS-Event-ID. See Webhooks for the event catalog and retry schedule.
import { constructWebhookEvent, WebhookVerificationError } from "@os-construction/sdk";
// Express: app.post("/hooks/os", express.raw({ type: "application/json" }), handler)
export async function handler(req, res) {
try {
const { event, eventId, body } = await constructWebhookEvent({
payload: req.body, // the raw bytes, before JSON parsing
headers: req.headers,
secret: process.env.OS_WEBHOOK_SECRET, // [old, new] while rotating
});
// de-duplicate on eventId, then handle event
res.sendStatus(204);
} catch (e) {
if (e instanceof WebhookVerificationError) return res.sendStatus(401);
throw e;
}
}import os_construction as osc
@app.post("/hooks/os") # Flask
def hook():
try:
evt = osc.construct_webhook_event(request.get_data(), request.headers,
os.environ["OS_WEBHOOK_SECRET"])
except osc.WebhookVerificationError:
abort(401)
# de-duplicate on evt.event_id, then handle evt.event / evt.body
return "", 204Building from source
For teams with access to the os.construction repository: both SDKs live under tools/ with build and verify scripts. The TypeScript package has no runtime dependencies (it uses the runtime's fetch and Web Crypto) and runs on Node.js 18+, Deno, Bun and modern browsers. The Python package needs Python 3.10+ and httpx.
# From a checkout of the os.construction repository
npm --prefix app ci
npm --prefix tools/sdk-ts run verify # build, tests, pack, install, typed consumer check
npm --prefix tools/sdk-ts pack # os-construction-sdk-0.1.0.tgz
cd tools/sdk-python
python -m venv .venv && .venv/Scripts/python -m pip install httpx pytest build hatchling mypy
.venv/Scripts/python scripts/verify.py # tests, mypy --strict, wheel, fresh-venv install
.venv/Scripts/python -m build # dist/os_construction-0.1.0-py3-none-any.whl