Permits
- GET
/rest/v1.0/companies/{company_id}/permits/work_queue - GET
/rest/v1.0/projects/{project_id}/permits - POST
/rest/v1.0/projects/{project_id}/permits - GET
/rest/v1.0/projects/{project_id}/permits/{id} - PATCH
/rest/v1.0/projects/{project_id}/permits/{id} - GET
/rest/v1.0/projects/{project_id}/permits/{id}/conditions - POST
/rest/v1.0/projects/{project_id}/permits/{id}/conditions - PATCH
/rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id} - PATCH
/rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}/follow_up - POST
/rest/v1.0/projects/{project_id}/permits/{id}/events - GET
/rest/v1.0/projects/{project_id}/permits/{id}/evidence_options
/rest/v1.0/companies/{company_id}/permits/work_queueGET 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.
Parameters
- company_idintegerpathrequired
- project_idintegerquery
- ownerstringqueryOne of: all, mine, unassigned.
- duestringqueryOne of: all, overdue, upcoming, undated.
- searchstringquery
- takeintegerquery
Response · 200 · object
- companyobjectrequired
- company.idintegerrequired
- company.namestringrequired
- projectsobject[]required
- projects[].idintegerrequired
- projects[].namestringrequired
- projects[].numberstring | nullrequired
- todaystring (date)required
- totalintegerrequired
- takeintegerrequired
- truncatedbooleanrequired
- filtersobjectrequired
- filters.project_idinteger
- filters.owneranyrequiredOne of: all, mine, unassigned.
- filters.dueanyrequiredOne of: all, overdue, upcoming, undated.
- filters.searchstringrequired
- filters.takeintegerrequired
- itemsobject[]required
- items[].idintegerrequired
- items[].kindanyrequiredOne of: condition, expiration.
- items[].projectobjectrequired
- items[].permit_idintegerrequired
- items[].permit_numberstringrequired
- items[].permit_titlestringrequired
- items[].descriptionstringrequired
- items[].due_onstring | null (date)required
- items[].owner_idinteger | nullrequired
- items[].owner_namestringrequired
- items[].owner_sourceanyrequiredOne of: condition, permit.
Errors
403Wrong company, inactive actor or missing permits:read token scope422Invalid or unsupported filter
Example request
curl -X GET "https://app.os.construction/rest/v1.0/companies/1/permits/work_queue" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/permitsGET projects/{project_id}/permits
Parameters
- project_idintegerpathrequired
- filters[status]stringquery
- searchstringquery
- pageintegerquery
- per_pageintegerquery
Response · 200 · object[]
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/permits" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/permitsPOST projects/{project_id}/permits
Parameters
- project_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- permitobjectrequired
- permit.titlestringrequired
- permit.authority_namestringrequired
- permit.jurisdiction_codestringrequired
- permit.permit_typestringrequired
- permit.scope_textstring
- permit.responsible_user_idinteger | null
Response · 201 · object
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- conditionsobject[]required
- conditions[].idintegerrequired
- conditions[].descriptionstringrequired
- conditions[].required_beforeanyrequiredOne of: issue, close.
- conditions[].due_onstring | null (date)required
- conditions[].assignee_user_idinteger | nullrequired
- conditions[].stateanyrequiredOne of: open, completed.
- conditions[].versionintegerrequired
- conditions[].completed_atstring | null (date-time)required
- conditions[].completed_by_idinteger | nullrequired
- conditions[].evidence_urlstring | nullrequired
- conditions[].missing_evidence_reasonstring | nullrequired
- conditions[].document_evidencenull | objectrequiredA 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.
- eventsobject[]required
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idintegerrequired
- events[].from_statusstring | nullrequired
- events[].to_statusstring | nullrequired
- events[].occurred_onstring | null (date)required
- events[].recorded_atstring (date-time)required
- events[].notestringrequired
- events[].authority_referencestring | nullrequired
- events[].evidence_urlstring | nullrequired
- events[].missing_evidence_reasonstring | nullrequired
- events[].expires_onstring | null (date)required
- events[].request_keystringrequired
- events[].document_evidencenull | objectrequiredA 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
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"
}
}'/rest/v1.0/projects/{project_id}/permits/{id}GET projects/{project_id}/permits/{id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- conditionsobject[]required
- conditions[].idintegerrequired
- conditions[].descriptionstringrequired
- conditions[].required_beforeanyrequiredOne of: issue, close.
- conditions[].due_onstring | null (date)required
- conditions[].assignee_user_idinteger | nullrequired
- conditions[].stateanyrequiredOne of: open, completed.
- conditions[].versionintegerrequired
- conditions[].completed_atstring | null (date-time)required
- conditions[].completed_by_idinteger | nullrequired
- conditions[].evidence_urlstring | nullrequired
- conditions[].missing_evidence_reasonstring | nullrequired
- conditions[].document_evidencenull | objectrequiredA 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.
- eventsobject[]required
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idintegerrequired
- events[].from_statusstring | nullrequired
- events[].to_statusstring | nullrequired
- events[].occurred_onstring | null (date)required
- events[].recorded_atstring (date-time)required
- events[].notestringrequired
- events[].authority_referencestring | nullrequired
- events[].evidence_urlstring | nullrequired
- events[].missing_evidence_reasonstring | nullrequired
- events[].expires_onstring | null (date)required
- events[].request_keystringrequired
- events[].document_evidencenull | objectrequiredA 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
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/permits/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/permits/{id}PATCH projects/{project_id}/permits/{id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- permitobjectrequired
- permit.versionintegerrequired
- permit.titlestring
- permit.authority_namestring
- permit.jurisdiction_codestring
- permit.permit_typestring
- permit.scope_textstring
- permit.responsible_user_idinteger | null
Response · 200 · object
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- conditionsobject[]required
- conditions[].idintegerrequired
- conditions[].descriptionstringrequired
- conditions[].required_beforeanyrequiredOne of: issue, close.
- conditions[].due_onstring | null (date)required
- conditions[].assignee_user_idinteger | nullrequired
- conditions[].stateanyrequiredOne of: open, completed.
- conditions[].versionintegerrequired
- conditions[].completed_atstring | null (date-time)required
- conditions[].completed_by_idinteger | nullrequired
- conditions[].evidence_urlstring | nullrequired
- conditions[].missing_evidence_reasonstring | nullrequired
- conditions[].document_evidencenull | objectrequiredA 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.
- eventsobject[]required
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idintegerrequired
- events[].from_statusstring | nullrequired
- events[].to_statusstring | nullrequired
- events[].occurred_onstring | null (date)required
- events[].recorded_atstring (date-time)required
- events[].notestringrequired
- events[].authority_referencestring | nullrequired
- events[].evidence_urlstring | nullrequired
- events[].missing_evidence_reasonstring | nullrequired
- events[].expires_onstring | null (date)required
- events[].request_keystringrequired
- events[].document_evidencenull | objectrequiredA 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
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
}
}'/rest/v1.0/projects/{project_id}/permits/{id}/conditionsGET projects/{project_id}/permits/{id}/conditions
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
Response · 200 · object[]
- idintegerrequired
- descriptionstringrequired
- required_beforeanyrequiredOne of: issue, close.
- due_onstring | null (date)required
- assignee_user_idinteger | nullrequired
- stateanyrequiredOne of: open, completed.
- versionintegerrequired
- completed_atstring | null (date-time)required
- completed_by_idinteger | nullrequired
- evidence_urlstring | nullrequired
- missing_evidence_reasonstring | nullrequired
- document_evidencenull | objectrequiredA 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
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/permits/1/conditions" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/permits/{id}/conditionsPOST projects/{project_id}/permits/{id}/conditions
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- conditionobjectrequired
- condition.expected_versionintegerrequired
- condition.descriptionstringrequired
- condition.required_beforeanyrequiredOne of: issue, close.
- condition.due_onstring | null (date)
- condition.assignee_user_idinteger | null
Response · 201 · object
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- conditionsobject[]required
- conditions[].idintegerrequired
- conditions[].descriptionstringrequired
- conditions[].required_beforeanyrequiredOne of: issue, close.
- conditions[].due_onstring | null (date)required
- conditions[].assignee_user_idinteger | nullrequired
- conditions[].stateanyrequiredOne of: open, completed.
- conditions[].versionintegerrequired
- conditions[].completed_atstring | null (date-time)required
- conditions[].completed_by_idinteger | nullrequired
- conditions[].evidence_urlstring | nullrequired
- conditions[].missing_evidence_reasonstring | nullrequired
- conditions[].document_evidencenull | objectrequiredA 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.
- eventsobject[]required
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idintegerrequired
- events[].from_statusstring | nullrequired
- events[].to_statusstring | nullrequired
- events[].occurred_onstring | null (date)required
- events[].recorded_atstring (date-time)required
- events[].notestringrequired
- events[].authority_referencestring | nullrequired
- events[].evidence_urlstring | nullrequired
- events[].missing_evidence_reasonstring | nullrequired
- events[].expires_onstring | null (date)required
- events[].request_keystringrequired
- events[].document_evidencenull | objectrequiredA 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
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"
}
}'/rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}PATCH projects/{project_id}/permits/{id}/conditions/{condition_id}
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- condition_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- conditionobjectrequiredProvide 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
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- conditionsobject[]required
- conditions[].idintegerrequired
- conditions[].descriptionstringrequired
- conditions[].required_beforeanyrequiredOne of: issue, close.
- conditions[].due_onstring | null (date)required
- conditions[].assignee_user_idinteger | nullrequired
- conditions[].stateanyrequiredOne of: open, completed.
- conditions[].versionintegerrequired
- conditions[].completed_atstring | null (date-time)required
- conditions[].completed_by_idinteger | nullrequired
- conditions[].evidence_urlstring | nullrequired
- conditions[].missing_evidence_reasonstring | nullrequired
- conditions[].document_evidencenull | objectrequiredA 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.
- eventsobject[]required
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idintegerrequired
- events[].from_statusstring | nullrequired
- events[].to_statusstring | nullrequired
- events[].occurred_onstring | null (date)required
- events[].recorded_atstring (date-time)required
- events[].notestringrequired
- events[].authority_referencestring | nullrequired
- events[].evidence_urlstring | nullrequired
- events[].missing_evidence_reasonstring | nullrequired
- events[].expires_onstring | null (date)required
- events[].request_keystringrequired
- events[].document_evidencenull | objectrequiredA 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
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": {}
}'/rest/v1.0/projects/{project_id}/permits/{id}/conditions/{condition_id}/follow_upPATCH 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.
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- condition_idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- conditionobjectrequired
- condition.expected_versionintegerrequired
- condition.versionintegerrequired
- condition.request_keystring (uuid)required
- condition.due_onstring | null (date)required
- condition.assignee_user_idinteger | nullrequired
- condition.reasonstringrequired
Response · 200 · object
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
Errors
403Permit edit access denied or tool disabled404Permit or nested condition not found in the project409Stale version, completed condition, terminal permit or conflicting request key422Invalid calendar date, assignee or request
Example request
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"
}
}'/rest/v1.0/projects/{project_id}/permits/{id}/eventsPOST projects/{project_id}/permits/{id}/events
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- Idempotency-KeystringheaderOptional. 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
- eventobjectrequiredProvide 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
- idintegerrequired
- company_idintegerrequired
- project_idintegerrequired
- numberstringrequired
- titlestringrequired
- authority_namestringrequired
- jurisdiction_codestringrequired
- permit_typestringrequired
- scope_textstringrequired
- authority_referencestring | nullrequired
- responsible_user_idinteger | nullrequired
- statusanyrequiredOne of: draft, submitted, corrections_required, approved, issued, suspended, closed, withdrawn.
- display_statusstringrequired
- versionintegerrequired
- submitted_onstring | null (date)required
- issued_onstring | null (date)required
- expires_onstring | null (date)required
- closed_onstring | null (date)required
- created_atstring (date-time)required
- updated_atstring (date-time)required
- conditionsobject[]required
- conditions[].idintegerrequired
- conditions[].descriptionstringrequired
- conditions[].required_beforeanyrequiredOne of: issue, close.
- conditions[].due_onstring | null (date)required
- conditions[].assignee_user_idinteger | nullrequired
- conditions[].stateanyrequiredOne of: open, completed.
- conditions[].versionintegerrequired
- conditions[].completed_atstring | null (date-time)required
- conditions[].completed_by_idinteger | nullrequired
- conditions[].evidence_urlstring | nullrequired
- conditions[].missing_evidence_reasonstring | nullrequired
- conditions[].document_evidencenull | objectrequiredA 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.
- eventsobject[]required
- events[].idintegerrequired
- events[].kindstringrequired
- events[].actor_user_idintegerrequired
- events[].from_statusstring | nullrequired
- events[].to_statusstring | nullrequired
- events[].occurred_onstring | null (date)required
- events[].recorded_atstring (date-time)required
- events[].notestringrequired
- events[].authority_referencestring | nullrequired
- events[].evidence_urlstring | nullrequired
- events[].missing_evidence_reasonstring | nullrequired
- events[].expires_onstring | null (date)required
- events[].request_keystringrequired
- events[].document_evidencenull | objectrequiredA 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
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": {}
}'/rest/v1.0/projects/{project_id}/permits/{id}/evidence_optionsGET 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.
Parameters
- project_idintegerpathrequired
- idintegerpathrequired
- searchstringquery
Response · 200 · object
- has_morebooleanrequired
- itemsobject[]required
- items[].document_version_idintegerrequired
- items[].file_idintegerrequired
- items[].namestringrequired
- items[].version_numberintegerrequired
- items[].content_typestringrequired
- items[].sizeintegerrequired
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/permits/1/evidence_options" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"