API Reference

The full, machine-readable API reference lives at docs.orkstra.com/api. It is generated from the live OpenAPI 3.1 spec and includes interactive try-it-out for every endpoint.

What's there

• 854 endpoints across 27 modules.
• Code samples in Python, JavaScript, curl, .NET.
• Schema definitions for every request and response.
• Authentication flows with worked examples.
• Error codes and remediation guidance.
• Postman collection for instant import.

Endpoint groups

The API is organized to mirror the modules:

Group	Description
auth	Login, refresh, MFA, recovery
tenants	Tenant settings, branding
companies	Company CRUD
projects	Project CRUD
boq	BOQ revisions, lines, import
ipcs	IPC create, submit, approve, certify
variations	VO create, price, agree, absorb
quality	Inspections, NCRs, punch lists
hse	Incidents, observations, permits
dms	Documents, folders, transmittals
tenders	Tender opportunity lifecycle
materials	Catalog, requests, GRNs, issues
assets	Equipment register, allocations, utilization
reports	Report execution + scheduling
admin	Users, roles, permissions, audit

OpenAPI spec

The raw OpenAPI spec is at:

https://api.orkstra.com/openapi.json

You can paste this URL into Swagger UI, Postman, Insomnia, or any other OpenAPI-aware tool.

Versioning

Endpoints carry a /v1 prefix. New major versions add /v2 etc. without removing the old.

Rate limits

• Default: 600 rpm per token, burst 50.
• Premium: 3000 rpm.
• 429 response includes Retry-After in seconds.

Pagination

List endpoints accept ?page and ?per_page (max 200). Responses include a pagination object with total, page, per_page, and next_page link.

Idempotency

Mutating endpoints accept an Idempotency-Key header. Same key + same payload within 24h returns the same response without re-executing.

Errors

Errors follow a consistent envelope:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Field 'quantity' must be positive.",
    "details": [{ "field": "quantity", "value": -1 }],
    "request_id": "req_01HXY..."
  }
}

Always log the request_id for support tickets.

See also: Webhooks, SDKs, API & Webhooks module.