Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Company Admin

58 endpoints58 implementedAll modules →
  1. GET /rest/v1.0/companies/{company_id}/departmentsList departments
  2. POST /rest/v1.0/companies/{company_id}/departmentsCreate departments
  3. GET /rest/v1.0/companies/{company_id}/departments/{id}Get departments
  4. PATCH /rest/v1.0/companies/{company_id}/departments/{id}Update departments
  5. DELETE /rest/v1.0/companies/{company_id}/departments/{id}Delete departments
  6. GET /rest/v1.0/companies/{company_id}/insurance_evidence_inboxRead current evidence awaiting review and route policy follow-ups
  7. GET /rest/v1.0/companies/{company_id}/insurance_followupsCompany-scoped renewal follow-up queue
  8. GET /rest/v1.0/companies/{company_id}/insurance_policiesList company insurance policies
  9. POST /rest/v1.0/companies/{company_id}/insurance_policiesCreate company insurance policy
  10. GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}Read company insurance policy
  11. PATCH /rest/v1.0/companies/{company_id}/insurance_policies/{id}Edit company insurance policy
  12. DELETE /rest/v1.0/companies/{company_id}/insurance_policies/{id}Delete company insurance policy
  13. GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidenceRead policy evidence and immutable history
  14. POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidenceReceive an immutable PDF or scan; receipt does not verify coverage
  15. GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidence/{evidence_id}/contentRead authorized evidence bytes, validating received SHA-256
  16. GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_upRead policy follow-up
  17. POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_upCreate, update, complete or reopen the single policy follow-up
  18. POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/renewalsCreate a linked renewal, preserving prior files and reviews
  19. POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/reviewsRecord evidence acceptance, rejection or revocation with a reason
  20. GET /rest/v1.0/companies/{company_id}/invitationsList invitations
  21. POST /rest/v1.0/companies/{company_id}/invitationsCreate invitation
  22. DELETE /rest/v1.0/companies/{company_id}/invitations/{id}Delete invitation
  23. GET /rest/v1.0/companies/{company_id}/migration_jobsList migration jobs
  24. POST /rest/v1.0/companies/{company_id}/migration_jobsCreate migration job
  25. GET /rest/v1.0/companies/{company_id}/migration_jobs/{id}Get migration job
  26. POST /rest/v1.0/companies/{company_id}/migration_jobs/{id}/runExecute the job
  27. GET /rest/v1.0/companies/{company_id}/officesList offices
  28. POST /rest/v1.0/companies/{company_id}/officesCreate offices
  29. GET /rest/v1.0/companies/{company_id}/offices/{id}Get offices
  30. PATCH /rest/v1.0/companies/{company_id}/offices/{id}Update offices
  31. DELETE /rest/v1.0/companies/{company_id}/offices/{id}Delete offices
  32. GET /rest/v1.0/companies/{company_id}/permission_templatesList company permission templates
  33. POST /rest/v1.0/companies/{company_id}/permission_templatesCreate company permission template
  34. GET /rest/v1.0/companies/{company_id}/permission_templates/{id}Read company permission template
  35. PATCH /rest/v1.0/companies/{company_id}/permission_templates/{id}Edit company permission template
  36. DELETE /rest/v1.0/companies/{company_id}/permission_templates/{id}Delete company permission template
  37. POST /rest/v1.0/companies/{company_id}/permission_templates/{id}/assignmentsAssign or clear a project permission template
  38. GET /rest/v1.0/companies/{company_id}/project_regionsList project regions
  39. POST /rest/v1.0/companies/{company_id}/project_regionsCreate project regions
  40. GET /rest/v1.0/companies/{company_id}/project_regions/{id}Get project regions
  41. PATCH /rest/v1.0/companies/{company_id}/project_regions/{id}Update project regions
  42. DELETE /rest/v1.0/companies/{company_id}/project_regions/{id}Delete project regions
  43. GET /rest/v1.0/companies/{company_id}/project_stages/{id}Get project stages
  44. PATCH /rest/v1.0/companies/{company_id}/project_stages/{id}Update project stages
  45. DELETE /rest/v1.0/companies/{company_id}/project_stages/{id}Delete project stages
  46. GET /rest/v1.0/companies/{company_id}/project_typesList project types
  47. POST /rest/v1.0/companies/{company_id}/project_typesCreate project types
  48. GET /rest/v1.0/companies/{company_id}/project_types/{id}Get project types
  49. PATCH /rest/v1.0/companies/{company_id}/project_types/{id}Update project types
  50. DELETE /rest/v1.0/companies/{company_id}/project_types/{id}Delete project types
  51. GET /rest/v1.0/companies/{company_id}/scim_connectionsList SCIM connections
  52. POST /rest/v1.0/companies/{company_id}/scim_connectionsCreate SCIM connection
  53. DELETE /rest/v1.0/companies/{company_id}/scim_connections/{id}Delete SCIM connection
  54. GET /rest/v1.0/companies/{company_id}/tradesList trades
  55. POST /rest/v1.0/companies/{company_id}/tradesCreate trades
  56. GET /rest/v1.0/companies/{company_id}/trades/{id}Get trades
  57. PATCH /rest/v1.0/companies/{company_id}/trades/{id}Update trades
  58. DELETE /rest/v1.0/companies/{company_id}/trades/{id}Delete trades
GET /rest/v1.0/companies/{company_id}/departments

List departments

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
    Values above 1000 are clamped by the REST handler.
  • search
    stringquery
    Trimmed, case-insensitive substring match on name; blank means no filter.

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/departments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/departments

Create departments

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • department
    objectrequired
  • department.name
    stringrequired
    Trimmed; must contain a non-whitespace character.
  • department.description
    string | null
  • department.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • department.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/departments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "department": {
    "name": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/departments/{id}

Get departments

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/departments/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/departments/{id}

Update departments

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • department
    objectrequired
  • department.name
    string
    Trimmed when nonblank; a whitespace-only name is ignored.
  • department.description
    string | null
  • department.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • department.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • description
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/departments/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "department": {}
}'
DELETE /rest/v1.0/companies/{company_id}/departments/{id}

Delete departments

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/departments/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/insurance_evidence_inbox

Read current evidence awaiting review and route policy follow-ups

Live company-admin authority and admin:read token scope are required. Replaced evidence is excluded from every filter and retained in policy history. Unreviewed, unassigned and mine exclude evidence with a recorded review. Unassigned has no open policy follow-up; mine has an open follow-up assigned to the caller. All returns current evidence regardless of review state. Oldest received first, ID tiebreaker. Only metadata is returned: view/review bytes through the existing policy evidence workflow. Acceptance is not coverage verification or payment release.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • filter
    stringquery
    One of: unreviewed, unassigned, mine, all.
  • kind
    stringquery
    One of: all, certificate, policy, endorsement.
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • evidence_id
    integerrequired
  • policy_id
    integerrequired
  • filename
    stringrequired
  • kind
    stringrequired
    One of: certificate, policy, endorsement.
  • received_at
    string (date-time)required
  • insurance_type
    stringrequired
  • policy_number
    string | nullrequired
  • review_status
    stringrequired
    One of: unreviewed, accepted, rejected, revoked.
  • follow_up
    object | nullrequired
  • follow_up.status
    stringrequired
    One of: open, completed.
  • follow_up.due_date
    string (date)required
  • follow_up.owner_name
    stringrequired
  • follow_up.owner_available
    booleanrequired

Errors

  • 401Authentication required
  • 403Current company-admin authority required
  • 404Wrong company
  • 422Invalid filter or pagination

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_evidence_inbox" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/insurance_followups

Company-scoped renewal follow-up queue

Overdue means before the current UTC day; due soon includes today through 30 days. Completed items are excluded from overdue/due-soon/mine. Each response page contains at most 25 items. Owners without live authority remain visible for reassignment. No notifications are sent.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • filter
    stringquery
    One of: open, overdue, due_soon, mine, completed, all.
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • policy_id
    integerrequired
  • owner_user_id
    integerrequired
  • owner_name
    stringrequired
  • owner_available
    booleanrequired
  • due_date
    string (date)required
  • status
    stringrequired
    One of: open, completed.
  • note
    stringrequired
  • completed_at
    string (date-time) | nullrequired
  • completed_by_id
    integer | nullrequired
  • linked_renewal_id
    integer | nullrequired
  • policy_version
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin required
  • 404Scoped policy, owner or renewal missing
  • 409Stale version, conflicting retry or invalid transition
  • 422Invalid input

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_followups" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/insurance_policies

List company insurance policies

Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Flat array ordered by expiration date then ID. Includes policies associated with historical inactive projects/vendors. No status or search filter. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • page
    integerquery
  • per_page
    integerquery
    Handler clamps values above 1000.
  • filters[project_id]
    integerquery
    Only the first positive integer value is used. Invalid values are ignored. Filters narrow the company register; they do not imply project membership.
  • filters[vendor_id]
    integerquery
    Only the first positive integer value is used. Invalid values are ignored. Filters narrow the company register; they do not imply project membership.

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • notes
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/insurance_policies

Create company insurance policy

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Project/vendor references must belong to this company; historical inactive references are permitted. Effective date cannot follow expiration date (400). Date-only inputs must be real calendar dates. Status in the response is pending without expiration, expired before the current instant, expiring within 30 days, otherwise active. JSON metadata only; no certificate upload. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • insurance_policy
    objectrequired
  • insurance_policy.insurance_type
    stringrequired
    Trimmed and must not be blank.
  • insurance_policy.carrier
    string | null
  • insurance_policy.policy_number
    string | null
  • insurance_policy.coverage_amount
    number | string | null
  • insurance_policy.effective_date
    string (date) | null
  • insurance_policy.expiration_date
    string (date) | null
  • insurance_policy.status
    string
    Optional stored status. The response always derives status freshly from expiration_date, so it may differ. One of: active, expiring, expired, pending.
  • insurance_policy.project_id
    integer | null
  • insurance_policy.vendor_id
    integer | null
  • insurance_policy.notes
    string | null

Response · 201 · object

  • id
    integerrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • notes
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "insurance_policy": {
    "insurance_type": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}

Read company insurance policy

Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Response status is computed from expiration at read time, regardless of stored status. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.

Response · 200 · object

  • id
    integerrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • notes
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/insurance_policies/{id}

Edit company insurance policy

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Omitted nullable fields retain their value; explicit null clears them. Remaining project/vendor references must belong to the company. Effective date cannot follow expiration date (400), including when only one date is changed. Response status is freshly derived even if an explicit stored status is supplied. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • insurance_policy
    objectrequired
  • insurance_policy.insurance_type
    string
    Trimmed and must not be blank.
  • insurance_policy.carrier
    string | null
  • insurance_policy.policy_number
    string | null
  • insurance_policy.coverage_amount
    number | string | null
  • insurance_policy.effective_date
    string (date) | null
  • insurance_policy.expiration_date
    string (date) | null
  • insurance_policy.status
    string
    Optional stored status. The response always derives status freshly from expiration_date, so it may differ. One of: active, expiring, expired, pending.
  • insurance_policy.project_id
    integer | null
  • insurance_policy.vendor_id
    integer | null
  • insurance_policy.notes
    string | null

Response · 200 · object

  • id
    integerrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • notes
    string | nullrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "insurance_policy": {}
}'
DELETE /rest/v1.0/companies/{company_id}/insurance_policies/{id}

Delete company insurance policy

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Permanently deletes the policy metadata record. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidence

Read policy evidence and immutable history

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • notes
    string | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • version
    integerrequired
  • renewed_from_id
    integer | nullrequired
  • renewal_id
    integer | nullrequired
  • evidence
    object[]required
  • evidence[].id
    integerrequired
  • evidence[].upload_id
    integerrequired
  • evidence[].storage_project_id
    integerrequired
  • evidence[].kind
    stringrequired
    One of: certificate, policy, endorsement.
  • evidence[].filename
    stringrequired
  • evidence[].content_type
    stringrequired
  • evidence[].size
    integerrequired
  • evidence[].sha256
    stringrequired
  • evidence[].policy_snapshot
    objectrequired
  • evidence[].received_by_id
    integerrequired
  • evidence[].received_at
    string (date-time)required
  • evidence[].replaces_evidence_id
    integer | nullrequired
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].evidence_id
    integer | nullrequired
  • events[].actor_user_id
    integerrequired
  • events[].kind
    stringrequired
    One of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
  • events[].decision
    string | nullrequired
    One of: accepted, rejected, revoked, null.
  • events[].note
    stringrequired
  • events[].request_key
    string (uuid)required
  • events[].policy_version
    integerrequired
  • events[].related_policy_id
    integer | nullrequired
  • events[].recorded_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin authority and source scopes required
  • 404Scoped resource not found
  • 409Stale version, conflicting retry, retained history or invalid transition
  • 422Invalid fields or unsupported evidence bytes

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/evidence" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidence

Receive an immutable PDF or scan; receipt does not verify coverage

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • expected_version
    integerrequired
  • request_key
    string (uuid)required
  • storage_project_id
    integerrequired
  • kind
    stringrequired
    One of: certificate, policy, endorsement.
  • note
    stringrequired
  • replaces_evidence_id
    integer
  • file
    string (binary)required

Response · 201 · object

  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • notes
    string | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • version
    integerrequired
  • renewed_from_id
    integer | nullrequired
  • renewal_id
    integer | nullrequired
  • evidence
    object[]required
  • evidence[].id
    integerrequired
  • evidence[].upload_id
    integerrequired
  • evidence[].storage_project_id
    integerrequired
  • evidence[].kind
    stringrequired
    One of: certificate, policy, endorsement.
  • evidence[].filename
    stringrequired
  • evidence[].content_type
    stringrequired
  • evidence[].size
    integerrequired
  • evidence[].sha256
    stringrequired
  • evidence[].policy_snapshot
    objectrequired
  • evidence[].received_by_id
    integerrequired
  • evidence[].received_at
    string (date-time)required
  • evidence[].replaces_evidence_id
    integer | nullrequired
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].evidence_id
    integer | nullrequired
  • events[].actor_user_id
    integerrequired
  • events[].kind
    stringrequired
    One of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
  • events[].decision
    string | nullrequired
    One of: accepted, rejected, revoked, null.
  • events[].note
    stringrequired
  • events[].request_key
    string (uuid)required
  • events[].policy_version
    integerrequired
  • events[].related_policy_id
    integer | nullrequired
  • events[].recorded_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin authority and source scopes required
  • 404Scoped resource not found
  • 409Stale version, conflicting retry, retained history or invalid transition
  • 422Invalid fields or unsupported evidence bytes

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/evidence" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_version": 1,
  "request_key": "00000000-0000-4000-8000-000000000000",
  "storage_project_id": 1,
  "kind": "certificate",
  "note": "string",
  "file": "string"
}'
GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}/evidence/{evidence_id}/content

Read authorized evidence bytes, validating received SHA-256

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • evidence_id
    integerpathrequired

Response · 200 · string (binary)

No documented fields.

Errors

  • 401Authentication required
  • 403Current company admin authority and source scopes required
  • 404Scoped resource not found
  • 409Stale version, conflicting retry, retained history or invalid transition
  • 422Invalid fields or unsupported evidence bytes

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/evidence/1/content" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_up

Read policy follow-up

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object | null

  • id
    integerrequired
  • policy_id
    integerrequired
  • owner_user_id
    integerrequired
  • owner_name
    stringrequired
  • owner_available
    booleanrequired
  • due_date
    string (date)required
  • status
    stringrequired
    One of: open, completed.
  • note
    stringrequired
  • completed_at
    string (date-time) | nullrequired
  • completed_by_id
    integer | nullrequired
  • linked_renewal_id
    integer | nullrequired
  • policy_version
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin required
  • 404Scoped policy, owner or renewal missing
  • 409Stale version, conflicting retry or invalid transition
  • 422Invalid input

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/follow_up" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/follow_up

Create, update, complete or reopen the single policy follow-up

Owner must currently have company admin authority. Completion is an administrative outcome only. Optional renewal must be the actual child of this policy. Reopen clears current completion/link and retains prior outcome in policy events. Commands require current policy version and a company-unique UUID; identical retries have no new effect.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • expected_version
    integerrequired
  • request_key
    string (uuid)required
  • note
    stringrequired
  • action
    stringrequired
  • owner_user_id
    integerrequired
  • due_date
    string (date)required

Response · 200 · object | null

  • id
    integerrequired
  • policy_id
    integerrequired
  • owner_user_id
    integerrequired
  • owner_name
    stringrequired
  • owner_available
    booleanrequired
  • due_date
    string (date)required
  • status
    stringrequired
    One of: open, completed.
  • note
    stringrequired
  • completed_at
    string (date-time) | nullrequired
  • completed_by_id
    integer | nullrequired
  • linked_renewal_id
    integer | nullrequired
  • policy_version
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin required
  • 404Scoped policy, owner or renewal missing
  • 409Stale version, conflicting retry or invalid transition
  • 422Invalid input

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/follow_up" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_version": 1,
  "request_key": "00000000-0000-4000-8000-000000000000",
  "note": "string",
  "action": "string",
  "owner_user_id": 1,
  "due_date": "2026-11-01"
}'
POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/renewals

Create a linked renewal, preserving prior files and reviews

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • expected_version
    integerrequired
  • request_key
    string (uuid)required
  • policy
    objectrequired
  • policy.insurance_type
    stringrequired
  • policy.carrier
    string | null
  • policy.policy_number
    string | null
  • policy.coverage_amount
    number | null
  • policy.effective_date
    string (date) | null
  • policy.expiration_date
    string (date) | null
  • policy.project_id
    integer | null
  • policy.vendor_id
    integer | null
  • policy.notes
    string | null
  • policy.status
    string
    One of: active, expiring, expired, pending.
  • note
    stringrequired

Response · 201 · object

  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • notes
    string | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • version
    integerrequired
  • renewed_from_id
    integer | nullrequired
  • renewal_id
    integer | nullrequired
  • evidence
    object[]required
  • evidence[].id
    integerrequired
  • evidence[].upload_id
    integerrequired
  • evidence[].storage_project_id
    integerrequired
  • evidence[].kind
    stringrequired
    One of: certificate, policy, endorsement.
  • evidence[].filename
    stringrequired
  • evidence[].content_type
    stringrequired
  • evidence[].size
    integerrequired
  • evidence[].sha256
    stringrequired
  • evidence[].policy_snapshot
    objectrequired
  • evidence[].received_by_id
    integerrequired
  • evidence[].received_at
    string (date-time)required
  • evidence[].replaces_evidence_id
    integer | nullrequired
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].evidence_id
    integer | nullrequired
  • events[].actor_user_id
    integerrequired
  • events[].kind
    stringrequired
    One of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
  • events[].decision
    string | nullrequired
    One of: accepted, rejected, revoked, null.
  • events[].note
    stringrequired
  • events[].request_key
    string (uuid)required
  • events[].policy_version
    integerrequired
  • events[].related_policy_id
    integer | nullrequired
  • events[].recorded_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin authority and source scopes required
  • 404Scoped resource not found
  • 409Stale version, conflicting retry, retained history or invalid transition
  • 422Invalid fields or unsupported evidence bytes

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/renewals" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_version": 1,
  "request_key": "00000000-0000-4000-8000-000000000000",
  "policy": {
    "insurance_type": "string"
  },
  "note": "string"
}'
POST /rest/v1.0/companies/{company_id}/insurance_policies/{id}/reviews

Record evidence acceptance, rejection or revocation with a reason

Review requires admin:read for the referenced source as well as admin:write. Acceptance records a document review, not verified coverage. Only an accepted review may be revoked. Every command requires current version and a company-unique request key; identical retries have no additional effect.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • expected_version
    integerrequired
  • request_key
    string (uuid)required
  • evidence_id
    integerrequired
  • decision
    stringrequired
    One of: accepted, rejected, revoked.
  • note
    stringrequired

Response · 200 · object

  • insurance_type
    stringrequired
  • carrier
    string | nullrequired
  • policy_number
    string | nullrequired
  • coverage_amount
    number | nullrequired
  • effective_date
    string (date) | nullrequired
  • expiration_date
    string (date) | nullrequired
  • project_id
    integer | nullrequired
  • vendor_id
    integer | nullrequired
  • notes
    string | nullrequired
  • status
    stringrequired
    One of: active, expiring, expired, pending.
  • id
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • version
    integerrequired
  • renewed_from_id
    integer | nullrequired
  • renewal_id
    integer | nullrequired
  • evidence
    object[]required
  • evidence[].id
    integerrequired
  • evidence[].upload_id
    integerrequired
  • evidence[].storage_project_id
    integerrequired
  • evidence[].kind
    stringrequired
    One of: certificate, policy, endorsement.
  • evidence[].filename
    stringrequired
  • evidence[].content_type
    stringrequired
  • evidence[].size
    integerrequired
  • evidence[].sha256
    stringrequired
  • evidence[].policy_snapshot
    objectrequired
  • evidence[].received_by_id
    integerrequired
  • evidence[].received_at
    string (date-time)required
  • evidence[].replaces_evidence_id
    integer | nullrequired
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].evidence_id
    integer | nullrequired
  • events[].actor_user_id
    integerrequired
  • events[].kind
    stringrequired
    One of: received, reviewed, renewed, renewal_created, metadata_updated, followup_create, followup_update, followup_complete, followup_reopen.
  • events[].decision
    string | nullrequired
    One of: accepted, rejected, revoked, null.
  • events[].note
    stringrequired
  • events[].request_key
    string (uuid)required
  • events[].policy_version
    integerrequired
  • events[].related_policy_id
    integer | nullrequired
  • events[].recorded_at
    string (date-time)required

Errors

  • 401Authentication required
  • 403Current company admin authority and source scopes required
  • 404Scoped resource not found
  • 409Stale version, conflicting retry, retained history or invalid transition
  • 422Invalid fields or unsupported evidence bytes

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/insurance_policies/1/reviews" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_version": 1,
  "request_key": "00000000-0000-4000-8000-000000000000",
  "evidence_id": 1,
  "decision": "accepted",
  "note": "string"
}'
GET /rest/v1.0/companies/{company_id}/invitations

List invitations

A scoped API token needs identity:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 201 · any[]

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.
  • 422Validation failed; `errors` maps each field to messages.

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/invitations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/invitations

Create invitation

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/invitations" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
DELETE /rest/v1.0/companies/{company_id}/invitations/{id}

Delete invitation

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/invitations/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/migration_jobs

List migration jobs

Requires the company admin permission. A scoped API token needs migration:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
    Page number, starting at 1.
  • per_page
    integerquery
    Records per page.

Request body

  • migration_job
    objectrequired
  • migration_job.target_project_id
    integer | null
  • migration_job.source_company_id
    string | null
  • migration_job.source_project_id
    string | null
  • migration_job.mode
    string
    One of: dry_run, live.
  • migration_job.scopes
    string[]
    One of: directory, rfis, submittals, punch_list, observations, daily_log, documents, prime_contracts, commitments.
  • migration_job.use_mock
    boolean
  • migration_job.source_base_url
    string | null
    One of: https://api.procore.com, https://sandbox.procore.com.
  • migration_job.source_token
    string | null

Response · 201 · object[]

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.
  • 422Validation failed; `errors` maps each field to messages.

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/migration_jobs" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "migration_job": {}
}'
POST /rest/v1.0/companies/{company_id}/migration_jobs

Create migration job

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/migration_jobs" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/migration_jobs/{id}

Get migration job

A scoped API token needs migration:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/migration_jobs/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/migration_jobs/{id}/run

Execute the job

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/migration_jobs/1/run" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/offices

List offices

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by main office first, then position and name. Includes inactive rows. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
    Values above 1000 are clamped by the REST handler.
  • search
    stringquery
    Trimmed, case-insensitive substring match on name; blank means no filter.

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state_code
    string | nullrequired
  • country_code
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • fax
    string | nullrequired
  • division
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • main_office
    booleanrequired

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/offices" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/offices

Create offices

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Setting main_office=true clears that flag on other company offices. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • office
    objectrequired
  • office.name
    stringrequired
    Trimmed; must contain a non-whitespace character.
  • office.address
    string | null
  • office.city
    string | null
  • office.state_code
    string | null
  • office.country_code
    string | null
  • office.zip
    string | null
  • office.phone
    string | null
  • office.fax
    string | null
  • office.division
    string | null
  • office.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • office.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
  • office.main_office
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state_code
    string | nullrequired
  • country_code
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • fax
    string | nullrequired
  • division
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • main_office
    booleanrequired

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/offices" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "office": {
    "name": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/offices/{id}

Get offices

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state_code
    string | nullrequired
  • country_code
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • fax
    string | nullrequired
  • division
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • main_office
    booleanrequired

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/offices/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/offices/{id}

Update offices

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Setting main_office=true clears that flag on other company offices. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • office
    objectrequired
  • office.name
    string
    Trimmed when nonblank; a whitespace-only name is ignored.
  • office.address
    string | null
  • office.city
    string | null
  • office.state_code
    string | null
  • office.country_code
    string | null
  • office.zip
    string | null
  • office.phone
    string | null
  • office.fax
    string | null
  • office.division
    string | null
  • office.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • office.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.
  • office.main_office
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • address
    string | nullrequired
  • city
    string | nullrequired
  • state_code
    string | nullrequired
  • country_code
    string | nullrequired
  • zip
    string | nullrequired
  • phone
    string | nullrequired
  • fax
    string | nullrequired
  • division
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • main_office
    booleanrequired

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/offices/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "office": {}
}'
DELETE /rest/v1.0/companies/{company_id}/offices/{id}

Delete offices

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/offices/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/permission_templates

List company permission templates

Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Flat array ordered by name; pagination slices the company template list. No search or type filter. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • page
    integerquery
  • per_page
    integerquery
    Handler clamps values above 1000.

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • project_specific
    booleanrequired
  • type
    stringrequired
    One of: global, project_specific.
  • permissions
    objectrequired

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/permission_templates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/permission_templates

Create company permission template

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Creates a project permission map; when analytics is omitted, creation inserts analytics:read_only. Creation does not assign the template or alter company admin flags. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • permission_template
    objectrequired
  • permission_template.name
    stringrequired
    Create trims and rejects blank names with 400. PATCH whitespace-only name is accepted but retains the existing name.
  • permission_template.project_specific
    any
    Boolean coercion uses JavaScript truthiness. Prefer a JSON boolean; a nonempty string, including "false", becomes true. Defaults false on create.
  • permission_template.permissions
    object
    Tool slug to permission level. PATCH replaces the whole map. Unknown tool keys are accepted; this does not grant company administrator status.

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • project_specific
    booleanrequired
  • type
    stringrequired
    One of: global, project_specific.
  • permissions
    objectrequired

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/permission_templates" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "permission_template": {
    "name": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/permission_templates/{id}

Read company permission template

Requires admin:read. Company path must match the authenticated tenant. Reads are available to active authenticated company members with the required token scope; no project-level membership gate. Returns the stored map, not the effective permissions of a user. Company admin overrides and workspace restrictions are evaluated separately. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • project_specific
    booleanrequired
  • type
    stringrequired
    One of: global, project_specific.
  • permissions
    objectrequired

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/permission_templates/{id}

Edit company permission template

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Supplying permissions replaces the whole map, including when empty; omitted keys lose template grants. Unlike creation, update does not add an analytics default. Changes affect all memberships assigned this template. project_specific is metadata, not a project restriction. This does not change company administrator flags. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • permission_template
    objectrequired
  • permission_template.name
    string
    Create trims and rejects blank names with 400. PATCH whitespace-only name is accepted but retains the existing name.
  • permission_template.project_specific
    any
    Boolean coercion uses JavaScript truthiness. Prefer a JSON boolean; a nonempty string, including "false", becomes true. Defaults false on create.
  • permission_template.permissions
    object
    Tool slug to permission level. PATCH replaces the whole map. Unknown tool keys are accepted; this does not grant company administrator status.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • project_specific
    booleanrequired
  • type
    stringrequired
    One of: global, project_specific.
  • permissions
    objectrequired

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "permission_template": {}
}'
DELETE /rest/v1.0/companies/{company_id}/permission_templates/{id}

Delete company permission template

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Clears this template from all valid company project memberships and permanently deletes it. Invalid retained foreign membership references fail with 400. Members may lose project grants; company administrator flags are not changed. No last-company-admin removal occurs through this operation. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
POST /rest/v1.0/companies/{company_id}/permission_templates/{id}/assignments

Assign or clear a project permission template

Requires admin:write. Company path must match the authenticated tenant. Writes require current company administrator authority; project-template admin permission alone is insufficient. Transactional services recheck authority. Requires an existing project membership and project, user and template in the authenticated company. The path template must exist even when clearing. Only explicit permission_template_id:null clears; omitted or numeric body values select the path template. Clearing removes template-derived project permissions, while company admin overrides remain. Assignment never creates membership or changes company administrator flags. Catalog presence does not grant access.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • OS-Company-Id
    integerheader
    Optional tenant assertion. Authenticated company is authoritative; this cannot select a different company.
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_id
    integerrequired
  • user_id
    integerrequired
  • permission_template_id
    integer | null
    Only explicit null clears. Omission or any accepted numeric value assigns the template identified by the URL, ignoring that numeric body value.

Response · 200 · object

  • project_id
    integerrequired
  • user_id
    integerrequired
  • permission_template_id
    integer | nullrequired

Errors

  • 400Invalid reference, date interval or retained membership references
  • 401Authentication required
  • 403Token scope or current company authority denied
  • 404Company or resource not found within the authenticated company
  • 422Body validation failed

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/permission_templates/1/assignments" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 1,
  "user_id": 1
}'
GET /rest/v1.0/companies/{company_id}/project_regions

List project regions

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
    Values above 1000 are clamped by the REST handler.
  • search
    stringquery
    Trimmed, case-insensitive substring match on name; blank means no filter.

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_regions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/project_regions

Create project regions

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_region
    objectrequired
  • project_region.name
    stringrequired
    Trimmed; must contain a non-whitespace character.
  • project_region.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • project_region.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/project_regions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_region": {
    "name": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/project_regions/{id}

Get project regions

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_regions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/project_regions/{id}

Update project regions

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_region
    objectrequired
  • project_region.name
    string
    Trimmed when nonblank; a whitespace-only name is ignored.
  • project_region.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • project_region.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/project_regions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_region": {}
}'
DELETE /rest/v1.0/companies/{company_id}/project_regions/{id}

Delete project regions

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Soft-deletes the record; later list/show omit it. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/project_regions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/project_stages/{id}

Get project stages

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • formatted_name
    stringrequired

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_stages/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/project_stages/{id}

Update project stages

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_stage
    objectrequired
  • project_stage.name
    string
    Trimmed when nonblank; a whitespace-only name is ignored.
  • project_stage.formatted_name
    string | null

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • formatted_name
    stringrequired

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/project_stages/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_stage": {}
}'
DELETE /rest/v1.0/companies/{company_id}/project_stages/{id}

Delete project stages

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/project_stages/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/project_types

List project types

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
    Values above 1000 are clamped by the REST handler.
  • search
    stringquery
    Trimmed, case-insensitive substring match on name; blank means no filter.

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_types" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/project_types

Create project types

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_type
    objectrequired
  • project_type.name
    stringrequired
    Trimmed; must contain a non-whitespace character.
  • project_type.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • project_type.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/project_types" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_type": {
    "name": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/project_types/{id}

Get project types

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/project_types/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/project_types/{id}

Update project types

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • project_type
    objectrequired
  • project_type.name
    string
    Trimmed when nonblank; a whitespace-only name is ignored.
  • project_type.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • project_type.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/project_types/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_type": {}
}'
DELETE /rest/v1.0/companies/{company_id}/project_types/{id}

Delete project types

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Soft-deletes the record; later list/show omit it. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/project_types/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
GET /rest/v1.0/companies/{company_id}/scim_connections

List SCIM connections

A scoped API token needs identity:read.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 201 · any[]

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.
  • 422Validation failed; `errors` maps each field to messages.

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/scim_connections" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/scim_connections

Create SCIM connection

v1.0Implemented

Parameters

  • company_id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/scim_connections" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
DELETE /rest/v1.0/companies/{company_id}/scim_connections/{id}

Delete SCIM connection

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

No documented fields.

Errors

  • 401Missing, invalid or expired API token.
  • 403The token or user lacks the required scope or permission.
  • 404The record does not exist or belongs to another company.

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/scim_connections/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
GET /rest/v1.0/companies/{company_id}/trades

List trades

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Returns a flat array, ordered by position and name. Includes inactive rows. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • page
    integerquery
  • per_page
    integerquery
    Values above 1000 are clamped by the REST handler.
  • search
    stringquery
    Trimmed, case-insensitive substring match on name; blank means no filter.

Response · 200 · object[]

  • id
    integerrequired
  • name
    stringrequired
  • code
    string | nullrequired
  • csi_code
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/trades" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/companies/{company_id}/trades

Create trades

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company create permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • trade
    objectrequired
  • trade.name
    stringrequired
    Trimmed; must contain a non-whitespace character.
  • trade.code
    string | null
  • trade.csi_code
    string | null
  • trade.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • trade.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 201 · object

  • id
    integerrequired
  • name
    stringrequired
  • code
    string | nullrequired
  • csi_code
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/companies/1/trades" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "trade": {
    "name": "string"
  }
}'
GET /rest/v1.0/companies/{company_id}/trades/{id}

Get trades

Requires admin:read. The company path must match the authenticated company; company identity comes from the token. Readable by an authenticated active company member with the token scope. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • code
    string | nullrequired
  • csi_code
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/trades/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/companies/{company_id}/trades/{id}

Update trades

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company edit permission, currently restricted to company administrators and subject to workspace restrictions. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Request body

  • trade
    objectrequired
  • trade.name
    string
    Trimmed when nonblank; a whitespace-only name is ignored.
  • trade.code
    string | null
  • trade.csi_code
    string | null
  • trade.active
    any
    Prefer a JSON boolean. The handler uses JavaScript Boolean coercion: null, 0 and empty string become false; nonempty strings (including "false"), arrays and objects become true. Omitted values keep the existing value on update.
  • trade.position
    any
    Prefer an integer. The handler applies JavaScript Number coercion and requires a safe integer; numeric strings, null (0), booleans (0/1) and coercible arrays are also accepted. Invalid or fractional results return 422. This server-side coercion is not fully expressible in JSON Schema.

Response · 200 · object

  • id
    integerrequired
  • name
    stringrequired
  • code
    string | nullrequired
  • csi_code
    string | nullrequired
  • active
    booleanrequired
  • position
    integerrequired
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/companies/1/trades/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "trade": {}
}'
DELETE /rest/v1.0/companies/{company_id}/trades/{id}

Delete trades

Requires admin:write. The company path must match the authenticated company; company identity comes from the token. Requires company delete permission, currently restricted to company administrators and subject to workspace restrictions. Permanently deletes the record. Catalog presence does not grant authorization.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • id
    integerpathrequired
  • Idempotency-Key
    stringheader
    Optional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.

Response · 204

No response body.

Errors

  • 400Malformed JSON, invalid service identity, or a blank name after trimming on create
  • 401Valid authentication required
  • 403Required token scope or company permission denied; workspace may be read only
  • 404Company path does not match the authenticated company, or the record does not exist in that company
  • 422Request body validation failed
  • 429Rate limit exceeded

Example request

Generated from the contractcurl
curl -X DELETE "https://app.os.construction/rest/v1.0/companies/1/trades/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file