Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Project Management

Permits

11 endpoints11 implementedAll modules →
  1. GET /rest/v1.0/companies/{company_id}/permits/work_queue
  2. GET /rest/v1.0/projects/{project_id}/permits
  3. POST /rest/v1.0/projects/{project_id}/permits
  4. GET /rest/v1.0/projects/{project_id}/permits/{id}
  5. PATCH /rest/v1.0/projects/{project_id}/permits/{id}
  6. GET /rest/v1.0/projects/{project_id}/permits/{id}/conditions
  7. POST /rest/v1.0/projects/{project_id}/permits/{id}/conditions
  8. PATCH /rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}
  9. PATCH /rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}/follow_up
  10. POST /rest/v1.0/projects/{project_id}/permits/{id}/events
  11. GET /rest/v1.0/projects/{project_id}/permits/{id}/evidence_options
GET /rest/v1.0/companies/{company_id}/permits/work_queue

GET companies/{company_id}/permits/work_queue

Read-only company permit queue. Requires current active company identity and exact permits:read token scope. Each project's current permit view permission and tool enablement are checked before gathering and again before publishing rows, totals or project options. Denied projects are omitted without hidden counts. Unexpected source errors fail the request. Includes open conditions on active permits and issued-permit expirations. Owner and UTC date semantics match the project queue. Returns only the first take tasks ordered by date (null last), condition before expiration, item ID, then project ID. Total is the sum of complete matching counts for currently authorized sources, not the number of returned tasks. No offset or next-page cursor; narrow filters to reach other work.

v1.0Implemented

Parameters

  • company_id
    integerpathrequired
  • project_id
    integerquery
  • owner
    stringquery
    One of: all, mine, unassigned.
  • due
    stringquery
    One of: all, overdue, upcoming, undated.
  • search
    stringquery
  • take
    integerquery

Response · 200 · object

  • company
    objectrequired
  • company.id
    integerrequired
  • company.name
    stringrequired
  • projects
    object[]required
  • projects[].id
    integerrequired
  • projects[].name
    stringrequired
  • projects[].number
    string | nullrequired
  • today
    string (date)required
  • total
    integerrequired
  • take
    integerrequired
  • truncated
    booleanrequired
  • filters
    objectrequired
  • filters.project_id
    integer
  • filters.owner
    anyrequired
    One of: all, mine, unassigned.
  • filters.due
    anyrequired
    One of: all, overdue, upcoming, undated.
  • filters.search
    stringrequired
  • filters.take
    integerrequired
  • items
    object[]required
  • items[].id
    integerrequired
  • items[].kind
    anyrequired
    One of: condition, expiration.
  • items[].project
    objectrequired
  • items[].permit_id
    integerrequired
  • items[].permit_number
    stringrequired
  • items[].permit_title
    stringrequired
  • items[].description
    stringrequired
  • items[].due_on
    string | null (date)required
  • items[].owner_id
    integer | nullrequired
  • items[].owner_name
    stringrequired
  • items[].owner_source
    anyrequired
    One of: condition, permit.

Errors

  • 403Wrong company, inactive actor or missing permits:read token scope
  • 422Invalid or unsupported filter

Example request

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

GET projects/{project_id}/permits

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • filters[status]
    stringquery
  • search
    stringquery
  • page
    integerquery
  • per_page
    integerquery

Response · 200 · object[]

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Example request

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

POST projects/{project_id}/permits

v1.0Implemented

Parameters

  • project_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

  • permit
    objectrequired
  • permit.title
    stringrequired
  • permit.authority_name
    stringrequired
  • permit.jurisdiction_code
    stringrequired
  • permit.permit_type
    stringrequired
  • permit.scope_text
    string
  • permit.responsible_user_id
    integer | null

Response · 201 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • conditions
    object[]required
  • conditions[].id
    integerrequired
  • conditions[].description
    stringrequired
  • conditions[].required_before
    anyrequired
    One of: issue, close.
  • conditions[].due_on
    string | null (date)required
  • conditions[].assignee_user_id
    integer | nullrequired
  • conditions[].state
    anyrequired
    One of: open, completed.
  • conditions[].version
    integerrequired
  • conditions[].completed_at
    string | null (date-time)required
  • conditions[].completed_by_id
    integer | nullrequired
  • conditions[].evidence_url
    string | nullrequired
  • conditions[].missing_evidence_reason
    string | nullrequired
  • conditions[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integerrequired
  • events[].from_status
    string | nullrequired
  • events[].to_status
    string | nullrequired
  • events[].occurred_on
    string | null (date)required
  • events[].recorded_at
    string (date-time)required
  • events[].note
    stringrequired
  • events[].authority_reference
    string | nullrequired
  • events[].evidence_url
    string | nullrequired
  • events[].missing_evidence_reason
    string | nullrequired
  • events[].expires_on
    string | null (date)required
  • events[].request_key
    stringrequired
  • events[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/permits" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "permit": {
    "title": "string",
    "authority_name": "string",
    "jurisdiction_code": "string",
    "permit_type": "string"
  }
}'
GET /rest/v1.0/projects/{project_id}/permits/{id}

GET projects/{project_id}/permits/{id}

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • conditions
    object[]required
  • conditions[].id
    integerrequired
  • conditions[].description
    stringrequired
  • conditions[].required_before
    anyrequired
    One of: issue, close.
  • conditions[].due_on
    string | null (date)required
  • conditions[].assignee_user_id
    integer | nullrequired
  • conditions[].state
    anyrequired
    One of: open, completed.
  • conditions[].version
    integerrequired
  • conditions[].completed_at
    string | null (date-time)required
  • conditions[].completed_by_id
    integer | nullrequired
  • conditions[].evidence_url
    string | nullrequired
  • conditions[].missing_evidence_reason
    string | nullrequired
  • conditions[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integerrequired
  • events[].from_status
    string | nullrequired
  • events[].to_status
    string | nullrequired
  • events[].occurred_on
    string | null (date)required
  • events[].recorded_at
    string (date-time)required
  • events[].note
    stringrequired
  • events[].authority_reference
    string | nullrequired
  • events[].evidence_url
    string | nullrequired
  • events[].missing_evidence_reason
    string | nullrequired
  • events[].expires_on
    string | null (date)required
  • events[].request_key
    stringrequired
  • events[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

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

PATCH projects/{project_id}/permits/{id}

v1.0Implemented

Parameters

  • project_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

  • permit
    objectrequired
  • permit.version
    integerrequired
  • permit.title
    string
  • permit.authority_name
    string
  • permit.jurisdiction_code
    string
  • permit.permit_type
    string
  • permit.scope_text
    string
  • permit.responsible_user_id
    integer | null

Response · 200 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • conditions
    object[]required
  • conditions[].id
    integerrequired
  • conditions[].description
    stringrequired
  • conditions[].required_before
    anyrequired
    One of: issue, close.
  • conditions[].due_on
    string | null (date)required
  • conditions[].assignee_user_id
    integer | nullrequired
  • conditions[].state
    anyrequired
    One of: open, completed.
  • conditions[].version
    integerrequired
  • conditions[].completed_at
    string | null (date-time)required
  • conditions[].completed_by_id
    integer | nullrequired
  • conditions[].evidence_url
    string | nullrequired
  • conditions[].missing_evidence_reason
    string | nullrequired
  • conditions[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integerrequired
  • events[].from_status
    string | nullrequired
  • events[].to_status
    string | nullrequired
  • events[].occurred_on
    string | null (date)required
  • events[].recorded_at
    string (date-time)required
  • events[].note
    stringrequired
  • events[].authority_reference
    string | nullrequired
  • events[].evidence_url
    string | nullrequired
  • events[].missing_evidence_reason
    string | nullrequired
  • events[].expires_on
    string | null (date)required
  • events[].request_key
    stringrequired
  • events[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/permits/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "permit": {
    "version": 1
  }
}'
GET /rest/v1.0/projects/{project_id}/permits/{id}/conditions

GET projects/{project_id}/permits/{id}/conditions

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired

Response · 200 · object[]

  • id
    integerrequired
  • description
    stringrequired
  • required_before
    anyrequired
    One of: issue, close.
  • due_on
    string | null (date)required
  • assignee_user_id
    integer | nullrequired
  • state
    anyrequired
    One of: open, completed.
  • version
    integerrequired
  • completed_at
    string | null (date-time)required
  • completed_by_id
    integer | nullrequired
  • evidence_url
    string | nullrequired
  • missing_evidence_reason
    string | nullrequired
  • document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

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

POST projects/{project_id}/permits/{id}/conditions

v1.0Implemented

Parameters

  • project_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

  • condition
    objectrequired
  • condition.expected_version
    integerrequired
  • condition.description
    stringrequired
  • condition.required_before
    anyrequired
    One of: issue, close.
  • condition.due_on
    string | null (date)
  • condition.assignee_user_id
    integer | null

Response · 201 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • conditions
    object[]required
  • conditions[].id
    integerrequired
  • conditions[].description
    stringrequired
  • conditions[].required_before
    anyrequired
    One of: issue, close.
  • conditions[].due_on
    string | null (date)required
  • conditions[].assignee_user_id
    integer | nullrequired
  • conditions[].state
    anyrequired
    One of: open, completed.
  • conditions[].version
    integerrequired
  • conditions[].completed_at
    string | null (date-time)required
  • conditions[].completed_by_id
    integer | nullrequired
  • conditions[].evidence_url
    string | nullrequired
  • conditions[].missing_evidence_reason
    string | nullrequired
  • conditions[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integerrequired
  • events[].from_status
    string | nullrequired
  • events[].to_status
    string | nullrequired
  • events[].occurred_on
    string | null (date)required
  • events[].recorded_at
    string (date-time)required
  • events[].note
    stringrequired
  • events[].authority_reference
    string | nullrequired
  • events[].evidence_url
    string | nullrequired
  • events[].missing_evidence_reason
    string | nullrequired
  • events[].expires_on
    string | null (date)required
  • events[].request_key
    stringrequired
  • events[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/permits/1/conditions" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "condition": {
    "expected_version": 1,
    "description": "string",
    "required_before": "issue"
  }
}'
PATCH /rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}

PATCH projects/{project_id}/permits/{id}/conditions/{condition_id}

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • condition_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

  • condition
    objectrequired
    Provide an HTTPS evidence reference or an explicit nonblank missing-evidence reason. Missing evidence remains visibly unverified. Whitespace-only text is rejected after trimming. Alternatively select evidence_document_version_id from the authorized evidence options. URL-only sample document versions cannot be attached. Uploaded evidence does not establish authenticity or authority approval.

Response · 200 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • conditions
    object[]required
  • conditions[].id
    integerrequired
  • conditions[].description
    stringrequired
  • conditions[].required_before
    anyrequired
    One of: issue, close.
  • conditions[].due_on
    string | null (date)required
  • conditions[].assignee_user_id
    integer | nullrequired
  • conditions[].state
    anyrequired
    One of: open, completed.
  • conditions[].version
    integerrequired
  • conditions[].completed_at
    string | null (date-time)required
  • conditions[].completed_by_id
    integer | nullrequired
  • conditions[].evidence_url
    string | nullrequired
  • conditions[].missing_evidence_reason
    string | nullrequired
  • conditions[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integerrequired
  • events[].from_status
    string | nullrequired
  • events[].to_status
    string | nullrequired
  • events[].occurred_on
    string | null (date)required
  • events[].recorded_at
    string (date-time)required
  • events[].note
    stringrequired
  • events[].authority_reference
    string | nullrequired
  • events[].evidence_url
    string | nullrequired
  • events[].missing_evidence_reason
    string | nullrequired
  • events[].expires_on
    string | null (date)required
  • events[].request_key
    stringrequired
  • events[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/permits/1/conditions/1" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "condition": {}
}'
PATCH /rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}/follow_up

PATCH projects/{project_id}/permits/{id}/conditions/{condition_id}/follow_up

Permit edit access required. Correct an open condition's recorded due date and assignee on a permit that is neither closed nor withdrawn. The assignee must be an active same-company project member. Null assignee restores permit-responsible-person fallback. Both versions must match. A material change increments both versions and appends history; an unchanged request does neither and does not reserve its request key. Identical material retries by the same actor replay without further changes, including after completion; reuse with changed payload returns 409. No completion, prerequisite, evidence or authority status changes are accepted.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • condition_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

  • condition
    objectrequired
  • condition.expected_version
    integerrequired
  • condition.version
    integerrequired
  • condition.request_key
    string (uuid)required
  • condition.due_on
    string | null (date)required
  • condition.assignee_user_id
    integer | nullrequired
  • condition.reason
    stringrequired

Response · 200 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required

Errors

  • 403Permit edit access denied or tool disabled
  • 404Permit or nested condition not found in the project
  • 409Stale version, completed condition, terminal permit or conflicting request key
  • 422Invalid calendar date, assignee or request

Example request

Generated from the contractcurl
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/permits/1/conditions/1/follow_up" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "condition": {
    "expected_version": 1,
    "version": 1,
    "request_key": "00000000-0000-4000-8000-000000000000",
    "due_on": "string",
    "assignee_user_id": 1,
    "reason": "string"
  }
}'
POST /rest/v1.0/projects/{project_id}/permits/{id}/events

POST projects/{project_id}/permits/{id}/events

v1.0Implemented

Parameters

  • project_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

  • event
    objectrequired
    Provide an HTTPS evidence reference or an explicit nonblank missing-evidence reason. Missing evidence remains visibly unverified. Whitespace-only text is rejected after trimming. The current permit state determines allowed transitions. Approval, issuance, renewal, suspension and closure require permits admin permission. Issuance requires all issuance conditions complete; closure requires every condition complete. A stale expected_version or reused request_key with changed payload returns 409. An identical retry returns the current permit without adding another event. Alternatively select evidence_document_version_id from the authorized evidence options. URL-only sample document versions cannot be attached. Uploaded evidence does not establish authenticity or authority approval.

Response · 200 · object

  • id
    integerrequired
  • company_id
    integerrequired
  • project_id
    integerrequired
  • number
    stringrequired
  • title
    stringrequired
  • authority_name
    stringrequired
  • jurisdiction_code
    stringrequired
  • permit_type
    stringrequired
  • scope_text
    stringrequired
  • authority_reference
    string | nullrequired
  • responsible_user_id
    integer | nullrequired
  • status
    anyrequired
    One of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
  • display_status
    stringrequired
  • version
    integerrequired
  • submitted_on
    string | null (date)required
  • issued_on
    string | null (date)required
  • expires_on
    string | null (date)required
  • closed_on
    string | null (date)required
  • created_at
    string (date-time)required
  • updated_at
    string (date-time)required
  • conditions
    object[]required
  • conditions[].id
    integerrequired
  • conditions[].description
    stringrequired
  • conditions[].required_before
    anyrequired
    One of: issue, close.
  • conditions[].due_on
    string | null (date)required
  • conditions[].assignee_user_id
    integer | nullrequired
  • conditions[].state
    anyrequired
    One of: open, completed.
  • conditions[].version
    integerrequired
  • conditions[].completed_at
    string | null (date-time)required
  • conditions[].completed_by_id
    integer | nullrequired
  • conditions[].evidence_url
    string | nullrequired
  • conditions[].missing_evidence_reason
    string | nullrequired
  • conditions[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.
  • events
    object[]required
  • events[].id
    integerrequired
  • events[].kind
    stringrequired
  • events[].actor_user_id
    integerrequired
  • events[].from_status
    string | nullrequired
  • events[].to_status
    string | nullrequired
  • events[].occurred_on
    string | null (date)required
  • events[].recorded_at
    string (date-time)required
  • events[].note
    stringrequired
  • events[].authority_reference
    string | nullrequired
  • events[].evidence_url
    string | nullrequired
  • events[].missing_evidence_reason
    string | nullrequired
  • events[].expires_on
    string | null (date)required
  • events[].request_key
    stringrequired
  • events[].document_evidence
    null | objectrequired
    A pinned real uploaded Documents version. Requires independent current Documents access and token documents:read scope. Denied, recycled or missing sources return only unavailable, without private source identifiers or names. A stored receipt is not a verification of authenticity.

Example request

Generated from the contractcurl
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/permits/1/events" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "event": {}
}'
GET /rest/v1.0/projects/{project_id}/permits/{id}/evidence_options

GET projects/{project_id}/permits/{id}/evidence_options

Search existing real uploaded Documents versions for this permit. Requires permit view and independent Documents view. Token callers also need documents:read. Results are bounded; refine search when has_more is true.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
  • id
    integerpathrequired
  • search
    stringquery

Response · 200 · object

  • has_more
    booleanrequired
  • items
    object[]required
  • items[].document_version_id
    integerrequired
  • items[].file_id
    integerrequired
  • items[].name
    stringrequired
  • items[].version_number
    integerrequired
  • items[].content_type
    stringrequired
  • items[].size
    integerrequired

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/permits/1/evidence_options" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"

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